@angar2/taskery 0.1.1 → 0.1.2

package/template/.claude/skills/plan-init/SKILL.md

@@ -66,7 +66,11 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
    - **ARCHITECTURE.md**: 시스템 구조 (멀티 리포 / 레이어드 / 마이크로서비스 등)
    - **DATA-MODEL.md** (해당 시): 주요 엔티티 + 관계
    - **API-SPEC.md**: 엔드포인트 목록 + 인증 방식
-   - **ROADMAP.md**: 마일스톤 + 시기 + 우선순위
+   - **ROADMAP.md**: 마일스톤 + 시기 + 우선순위. *ROADMAP 작성 4룰* (stash FRICTION_LOG #1 반영):
+     1. ROADMAP은 *현재 버전 한정* — 미래 버전 후보는 별도 `BACKLOG.md` (글로벌) 분리
+     2. 진행 순서에 task 번호(TASK-NNN) 강제 금지 — *Stage(영역) 단위*로만 명시 (예측 불가 task 합류 시 번호 어긋남 방지)
+     3. Stage 안 *작업 단위 명시* 필요 (한 task 분량 권장 — 다음 task 진행 시 메인 세션이 ROADMAP 보고 작업 범위 판단 가능)
+     4. 작업 단위에 task 번호 컬럼 추가 X / *상태 컬럼만* (⏳ 대기 / 🔧 진행 중 / ✅ 완료 / ❌ 폐기) — Living document
 4. 받은 답 기반으로 각 문서 작성.
 5. 마지막에 **PLAN.md** 작성 — 9 문서 인덱스 + 체크리스트.
 6. **`.project/AGENT-GUIDE.md`의 활성 plan 버전 vX.X로 갱신** (신규도 동일 — 분기 2와 일관).
@@ -84,7 +88,26 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
 ### Step 5 — `tasks/<vX.X>/` 디렉토리 준비
 
 1. `.project/tasks/<vX.X>/` 디렉토리 생성 (빈 폴더).
-2. `.project/tasks/<vX.X>/spec-diffs/`, `.project/tasks/<vX.X>/screenshots/` 빈 폴더 미리 생성.
+2. `.project/tasks/<vX.X>/spec-diffs/`, `.project/tasks/<vX.X>/screenshots/`, `.project/tasks/<vX.X>/mockup/` 빈 폴더 미리 생성.
+3. `.project/tasks/<vX.X>/BACKLOG.md` 빈 골격 Write (stash FRICTION_LOG #17 반영) — *버전별 task 후보 누적용*, 글로벌 `.project/BACKLOG.md`와 별개:
+
+```markdown
+# BACKLOG — <vX.X>
+
+> 본 파일은 *<vX.X> plan 진행 중 누적되는 후속 task 후보* 추적용.
+> 글로벌 `.project/BACKLOG.md` (plan 기획 후보 카탈로그) 와 별개.
+
+| 위치 | 영역 | 역할 |
+|------|------|------|
+| `.project/BACKLOG.md` (글로벌) | plan 기획 후보 카탈로그 (다음 plan 버전에서 검토) | Living document |
+| `.project/tasks/<vX.X>/BACKLOG.md` (본 파일) | 현재 plan 진행 중 누적된 후속 task 후보 | 한 버전 내 task close 직후 후보 누적 |
+
+## 후속 task 후보
+
+(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)
+```
+
+빈 골격만 작성. 본문은 task 진행하면서 사용자 발화 또는 메인 감지로 누적.
 
 ### Step 6 — `PLAN.md` 작성/갱신
 
@@ -119,12 +142,12 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
 **결과 commit 흐름** (GIT_RULE 정합):
 - dev 직접 commit *금지* (git-guard.sh 차단). 두 가지 default 흐름:
   1. **첫 task에 묶기 (권장)**: 분기 1(신규)에서 `/project-init` 직후 본 스킬 호출이면 `/project-init` 산출물과 같은 작업 브랜치(보통 TASK-001 부트스트랩 chore)에 함께 commit. 분기 2(이어가기)면 새 task 브랜치 또는 임시 docs 브랜치에서.
-  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_plan-{vX.X}` 후 commit → dev에 `--no-ff` 머지. 다음 task 생성 *전*에 plan 산출물을 깔끔히 박고 싶을 때.
+  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_plan-{vX.X}` 후 commit → dev에 `--no-ff` 머지. 다음 task 생성 *전*에 plan 산출물을 깔끔히 기록하고 싶을 때.
 
 ## 도구 가이드
 
 - **Read**: PROJECT.md / 기존 plans/vY.Y/ 정독
-- **Bash**: `ls .project/plans/`, `cp -r plans/vY.Y plans/vX.X`, `mkdir -p plans/<vX.X> tasks/<vX.X>/{spec-diffs,screenshots}`
+- **Bash**: `ls .project/plans/`, `cp -r plans/vY.Y plans/vX.X`, `mkdir -p plans/<vX.X> tasks/<vX.X>/{spec-diffs,screenshots,mockup}`
 - **Write/Edit**: 9 기획 문서 작성/갱신
 - **AskUserQuestion**: 9 문서별 핵심 질문 + 변경 인터뷰
 

package/template/.claude/skills/project-init/SKILL.md

@@ -92,7 +92,9 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 1. `CLAUDE.md` — 프로젝트 메타 + 검증 명령 + 룰 참조
 2. `.project/PROJECT.md` — 프로젝트 개요
 3. `.project/plans/<활성버전>/PLAN.md` — 활성 plan 진입 (이게 9 기획 문서 인덱스)
-4. `.project/AGENT-GUIDE.md` — 본 파일 (그대로)
+4. `.project/GLOSSARY.md` — 도메인 용어집 (영문/한글 표기 일관성 단일 진실 소스)
+5. `.project/tasks/<활성버전>/BACKLOG.md` — 현재 plan 진행 중 누적된 후속 task 후보 (사용자 발화 *"이건 다음 task로"* / task-close 직후 메인 감지로 추가)
+6. `.project/AGENT-GUIDE.md` — 본 파일 (그대로)
 
 ## 작업 흐름
 - task 시작: `/task-init` 또는 `/task-plan`
@@ -100,7 +102,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 - 불편 등록: `/log-friction` (사용자 호출 / 발화 캐치 / task-close 자체 감지)
 
 ## 폴더 구조
-- `.project/rules/` — 코어 룰 (TASK_DOC_RULE / GIT_RULE)
+- `.project/rules/` — 코어 룰 (TASK_DOC_RULE / GIT_RULE / CHANGELOG_RULE / MOCKUP_RULE)
 - `.project/plans/<vX.X>/` — 9 기획 문서
 - `.project/tasks/<vX.X>/` — task 문서
 - `.project/flows/` — 도메인 흐름
@@ -113,8 +115,33 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 멀티 리포면 "LINKED-REPOS.md 참조">
 ```
 
+### Step 4.5 — `.project/GLOSSARY.md` 작성 (도메인 용어집)
+
+stash FRICTION_LOG #3 반영 — 프로젝트 도메인 용어를 *영문/한글 표기 일관성* 단일 진실 소스로 모음. 코드 메서드명·변수명 / 대화·문서 한글 표기 통일.
+
+```markdown
+# GLOSSARY — <프로젝트명>
+
+> 본 프로젝트에서 사용하는 도메인 용어집. 코드 식별자 / 문서 / 대화 모두 본 표 기준.
+> 새 용어 추가 시 영문 알파벳 순 정렬 유지.
+
+| 영문 | 한글 | 정의 | 출처 |
+|------|------|------|------|
+| | | | |
+
+## 운용 룰
+
+- 영문 알파벳 순 정렬
+- 출처: 본 용어가 도입된 task/plan 문서 경로 (예: `plans/v1.0/FEATURES.md`)
+- 동의어 / 변형 표기 발견 시 본 표 기준으로 정합
+```
+
+빈 표만 작성. 본문은 plan/task 진행하면서 사용자가 채움.
+
 ### Step 5 — `.project/LINKED-REPOS.md` 작성
 
+멀티리포 구성 명세. 단일 리포면 빈 템플릿만, 멀티 리포면 연결 리포 목록까지.
+
 ```markdown
 # LINKED-REPOS.md
 
@@ -153,7 +180,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 - `.project/tasks/` (`.gitkeep` — `/task-init`이 `vX.X/<NNN>_<slug>.md` 작성)
 - `.project/shared/{sent,received}/completed/` (`.gitkeep`)
 - `.project/FRICTION_LOG.md` (빈 템플릿)
-- `.project/rules/{TASK_DOC_RULE,GIT_RULE}.md` (코어 룰)
+- `.project/rules/{TASK_DOC_RULE,GIT_RULE,CHANGELOG_RULE,MOCKUP_RULE}.md` (코어 룰)
 
 → `/project-init`은 폴더 생성 X. 누락 시(`init` 안 거치고 수동 셋업한 경우)에만 `mkdir -p` 실행.
 
@@ -193,12 +220,12 @@ git branch -a                                        # main(또는 master) + dev
 ### Step 8 — 결과 보고
 
 작성된 파일 목록 + 다음 단계 안내:
-- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). **빈 폴더 케이스라 git init + dev 분기까지 완료** (이미 git 리포면 건너뜀). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
+- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / GLOSSARY.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). **빈 폴더 케이스라 git init + dev 분기까지 완료** (이미 git 리포면 건너뜀). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
 
 **결과 commit 흐름** (GIT_RULE 정합):
 - dev 직접 commit *금지* (git-guard.sh 차단). 두 가지 default 흐름:
   1. **첫 task에 묶기 (권장)**: `/plan-init` 끝나고 첫 `/task-init` (보통 TASK-001 부트스트랩 chore)으로 만든 작업 브랜치에서 init 산출물(PROJECT/AGENT-GUIDE/LINKED-REPOS/.env)도 함께 commit. task-close 단계의 "태스크 문서 커밋"에 자연스럽게 묶임.
-  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_init-bootstrap` 후 commit → dev에 `--no-ff` 머지. 첫 task 생성 *전*에 init 결과를 깔끔히 박고 싶을 때.
+  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_init-bootstrap` 후 commit → dev에 `--no-ff` 머지. 첫 task 생성 *전*에 init 결과를 깔끔히 기록하고 싶을 때.
 
 ## 도구 가이드
 

package/template/.claude/skills/task-close/SKILL.md

@@ -1,189 +1,338 @@
 ---
 name: task-close
-description: task git 마무리 — 검증 명령 재실행 게이트 + 커밋 순서 준수 + dev --no-ff 병합, tested → closed
+description: task git 마무리 — 검증 게이트 + 커밋 순서 + 머지 락 직렬화 + dev --no-ff 병합 + 워크트리/브랜치 자동 정리, tested → closed (멀티세션 0.1.2+)
 ---
 
 # /task-close
 
 ## 개요
 
-`tested` 상태 task의 git 마무리. 작업 브랜치(없으면 생성)에서 커밋 순서(GIT_RULE 준수) 따라 진행 + dev 병합 + status `closed`.
+`tested` 상태 task의 git 마무리. **워크트리에서 호출** 권장. 사전 rebase → 충돌 해결 (3단계 에스컬레이션) → 머지 락 → 락 안 재 rebase → dev `--no-ff` 머지 → 워크트리 제거 + 작업 브랜치 자동 삭제.
 
-**최종 게이트**: 모든 검증 명령 재실행 — 린트/타입체크/빌드/단위테스트 PASS여야 진행.
+**최종 게이트**: 모든 검증 명령 재실행 — 린트/타입체크/빌드 PASS여야 진행.
 
 ## 호출 시점
 
 - `/task-test` PASS 후 + 사용자 OK.
 - `/task-test` FAIL 후 사용자 *"OK 마무리"* (알려진 결함 명시 채로).
 
+## 호출 위치 정책
+
+- **워크트리에서 호출 권장** (CWD = 워크트리 폴더).
+- **메인 워크트리에서 호출 시** → 진행중 태스크 목록 인터뷰 + 사용자 선택 → 해당 워크트리 컨텍스트로 진행.
+
 ## 입력 처리
 
 인자 = (선택) `TASK-NNN` 또는 자동 선택.
 
 분기:
-- **인자 명시**: 해당 task 파일.
-- **인자 없음**: 활성 plan 버전의 *상태=tested인 가장 최근 task* 자동 선택 + confirm.
+- **인자 명시**: 해당 task.
+- **인자 없음**: 워크트리에서 호출 시 *그 워크트리의 태스크* 자동 / 메인에서 호출 시 *상태=tested 가장 최근 task* 인터뷰.
+
+## 핵심 변수
+
+```sh
+MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+WT_PATH=$(pwd)  # 워크트리에서 호출됐다고 가정 (메인 호출 시 사용자 선택 결과)
+PROJECT_ID=$(jq -r '.projectId' "$MAIN_WT/.taskery-manifest.json")
+BRANCH=$(git -C "$WT_PATH" rev-parse --abbrev-ref HEAD)
+LOCK_TIMEOUT_MS=$(jq -r '.lock_timeout_ms // 30000' "$MAIN_WT/.taskery-manifest.json")
+LOCK_FILE="$HOME/.taskery/${PROJECT_ID}.merge.lock"
+```
 
 ## 단계
 
-### Step 1 — task 파일 + GIT_RULE 확인
+### Step 1 — 사전 검증
 
-1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
-2. task 파일 Read:
-   - 인자 있음 → 해당 파일.
-   - 인자 없음 → `tested` 상태 가장 최근 task. confirm. 없으면 *"마무리할 task 없음."* + 종료.
-3. 상태 = `tested` 검증. 그 외면 종료 (단 알려진 결함 *"OK 마무리"*는 status=tested로 명시되어 있어야 함).
-4. GIT_RULE Read 우선순위:
-   - `.project/rules/GIT_RULE.md` (프로젝트별 — 우선)
-   - `~/.claude/rules/GIT_RULE.md` (글로벌)
-   둘 다 없으면 종료 + *"GIT_RULE 누락"* 보고.
+1. **메인 워크트리 검출** (위 핵심 변수).
+2. **메인 워크트리 = dev 검증**:
+   ```sh
+   CURRENT=$(git -C "$MAIN_WT" rev-parse --abbrev-ref HEAD)
+   [ "$CURRENT" = "dev" ] || abort "메인 워크트리가 dev 아님 (현재: $CURRENT). taskery 정책 위배"
+   ```
+3. **워크트리 미커밋 변경 확인**:
+   ```sh
+   git -C "$WT_PATH" status --porcelain
+   ```
+   - 결과 *있음* = 정상 흐름 (taskery 정책: `/task-dev` = *git 작업 X*). 본 변경분은 Step 6-3에서 *task-close가 자동 Phase 커밋 생성*으로 처리.
+   - 결과 *없음* = 변경분 0건 → Step 2 검증만 수행 후 Step 6-3 자동 커밋 단계 자연 스킵 (빈 커밋 X).
+   - **차단 X** — 본 단계는 *상태 인지*용. close 중단 사유 X.
+4. **task 파일 + GIT_RULE 확인**:
+   - task 문서 위치 분기 (`.gitignore` 케이스):
+     ```sh
+     git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
+     ```
+     - exit 0 (등록됨): `$MAIN_WT/.project/tasks/<vX.X>/...` (단일 소스)
+     - exit 1 (미등록): `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안)
+   - 상태 = `tested` 검증. 그 외면 종료 (단 알려진 결함 *"OK 마무리"*는 status=tested로 명시되어 있어야 함).
+   - GIT_RULE Read 우선순위:
+     - `$MAIN_WT/.project/rules/GIT_RULE.md` (프로젝트별 — 우선)
+     - `~/.claude/rules/GIT_RULE.md` (글로벌)
+     둘 다 없으면 종료 + *"GIT_RULE 누락"* 보고.
 
 ### Step 2 — 최종 검증 명령 재실행 (게이트)
 
-`CLAUDE.md`의 *검증 명령* 모두 재실행. **하나라도 FAIL이면 close 차단**:
+`$MAIN_WT/CLAUDE.md`의 `## 검증 명령` (빌드/린트/타입체크) 만 재실행. **하나라도 FAIL이면 close 차단**.
 
 | 명령 | 결과 |
 |------|------|
 | 린트 | exit 0 + 에러 0 |
 | 타입체크 | exit 0 |
 | 빌드 | exit 0 |
-| 단위 테스트 | 모든 케이스 PASS |
+
+> 테스트 명령은 본 게이트에서 실행 X. `/task-test` 격리 세션이 단일 시점 (stash FRICTION_LOG #25).
+
+> **검증 명령 실행 위치**: 워크트리(`$WT_PATH`)에서. 코드 변경은 워크트리 안에 있으므로 검증 대상도 거기.
 
 FAIL 시:
 - 사용자에게 보고 — *"검증 명령 X가 FAIL. 어떻게 할까?"*
 - 분기:
-  - *"고쳐"* → status를 `developing`으로 되돌림 + `/task-dev` 안내 + close 중단.
+  - *"고쳐"* → status `developing`으로 되돌림 + `/task-dev` 안내 + close 중단.
   - *"OK 마무리"* → 결함 명시한 채 진행 (Result 섹션에 *"검증 명령 X FAIL 알려진 결함 — 사유: ..."* 추가).
 
-PASS 시 Step 3으로.
+### Step 3 — 사전 rebase (락 외, UX용 조기 충돌 감지)
 
-### Step 3 — 작업 브랜치 확인/생성
+```sh
+git -C "$WT_PATH" rebase dev
+```
 
-1. `git branch --show-current` 실행 → 현재 브랜치 확인.
-2. 분기:
-   - **현재 브랜치 = `{타입}/{개발자}_TASK-<NNN>_<slug>`** → 그대로 진행.
-   - **현재 브랜치 = `dev`** (또는 다른 곳) → 새 작업 브랜치 생성:
-     ```
-     git checkout -b {타입}/{개발자}_TASK-<NNN>_<slug>
-     ```
-     - **타입**: feature → `feature`, bug → `bug`, improvement → `improve`, refactor → `refactor`, docs → `docs`, chore → `chore`
-     - **개발자**: 메인 세션 = `claude`, 사용자 세션 = `angar2` 등 (실제 작업자)
-     - **slug**: task 파일명에서 그대로
-     - 예: `feature/claude_TASK-007_login-feature`
-3. 작업 브랜치 진입 후 *변경분이 미리 stage* 되어 있어야 함. dev에서 작업했다면 이미 working tree에 변경분 있음 — 그대로 새 브랜치 진입 후 staging.
-4. **작업 브랜치 생성과 staging/commit은 별도 Bash 호출로 분리**. `git checkout -b ... && git add ... && git commit ...` 같이 `&&`로 묶으면 git-guard.sh가 *명령 텍스트 분석 시점*에 dev 브랜치로 판정해 commit을 차단함 (분리하면 정상 통과). 묶음 명령 default X.
+- 충돌 없음 → Step 6으로 (커밋 순서).
+- 충돌 있음 → Step 4 (3단계 에스컬레이션).
 
-### Step 4 — 커밋 (GIT_RULE 순서 준수)
+### Step 4 — 충돌 자체 해결 (3단계 에스컬레이션)
 
-**필수 순서**:
+#### 4-a. 단순 충돌 → 자동 해결
 
-1. **Phase별 기능 커밋** — Dev Plan의 각 Phase마다 1개 커밋.
-   - 같은 파일이 여러 Phase에 걸쳐 변경됐으면 *단일 통합 커밋 1개*로 묶음. 커밋 메시지 본문에 Phase별 변경을 `-`로 나열, 헤더 태그/번호는 마지막 Phase 사용.
-   - 메시지 형식 (GIT_RULE.md):
-     ```
-     {태그}: [TASK-<NNN>] Phase <N> - <작업 요약>
+- 공백 / 의미 같은 코드 차이 / 주석 / 명백한 add-add
+- 자동 해결 후 `git -C "$WT_PATH" rebase --continue`
 
-     - <처리 내용 1>
-     - <처리 내용 2>
-     - 사유: <변경 이유>
-     ```
-   - 태그: feature → `feat:`, bug → `fix:`, improvement → `improve:`, refactor → `refactor:`, docs/chore → `docs:`, 테스트 파일 → `test:`
-2. **flows/ 모듈 커밋 (해당 시)** — `.project/flows/<module>.md` 변경분 있으면 별도 커밋:
-   ```
-   docs: [TASK-<NNN>] flows/<module>.md 갱신
+#### 4-b. 의미적 충돌 → 자료 분석
 
-   - <변경 요약>
-   - 사유: <변경 이유>
-   ```
-3. **태스크 문서 커밋**:
-   ```
-   docs: [TASK-<NNN>] 태스크 문서 완료
+**자료 우선순위**:
+
+| 순위 | 자료 | 위치 |
+|------|------|------|
+| 1 | 태스크 문서 + plan 문서 (양쪽 정독 후 의도 종합) | 태스크: `$MAIN_WT/.project/tasks/<vX.X>/...` (등록 케이스) / `~/.taskery/worktrees/<projectId>/TASK-...` 다른 워크트리 (미등록 케이스, SSoT 조회로 경로 산출). plan: `$MAIN_WT/.project/plans/<vX.X>/` (ROADMAP / FEATURES / ARCHITECTURE / TECH-STACK 등) |
+| 2 | 커밋 메시지 | `git log dev --grep` (GIT_RULE 풍부 메시지) |
+| 3 | diff | 변경 코드 자체 |
+
+- 1순위 부재 시 2/3순위 자동 fallback + 사용자에게 *자료 한계* 보고
+- 태스크 문서 = 본 task의 *세부 의도* / plan 문서 = *전체 의도* (Stage 순 / 의존 그래프 / 의도된 위치 분리). 충돌 영역의 *그림 전체*는 plan 문서가 더 명확한 경우 많음 (Stage 순서로 *먼저 머지된 쪽 다음 줄에 추가* 등)
+- 정독 후 *의미 의도 추출* → 충돌 해결 → `git rebase --continue`
+
+#### 4-c. 판단 불가 → 사용자 호출
+
+- 해결 방향 후보 제시 + 사용자 결정 후 재개.
+- 사용자가 중단 결정 시: `git -C "$WT_PATH" rebase --abort` 자동 + close 중단.
+
+### Step 5 — 태스크 문서에 충돌 해결 내역 추가 (해당 시)
+
+충돌 해결 1건이라도 발생했으면 task 문서에 기록.
+
+`.gitignore` 케이스 분기:
+
+| 케이스 | 위치 | 흐름 |
+|--------|------|------|
+| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` | 워크트리 안 task 문서 수정 → Step 6 Phase 커밋에 *코드 + 문서 = 한 커밋*에 포함 |
+| 등록 | `$MAIN_WT/.project/tasks/<vX.X>/...` | 워크트리 안 코드만 한 커밋 + 메인 워크트리 절대 경로 task 문서를 **proper-lockfile**로 별도 수정 (`bin/lib.js` `withMetaLock` — 머지 커밋 미포함, 메인 로컬 보존) |
+
+기록 형식 (task.md Result 섹션 안):
+```markdown
+### 충돌 해결 (close 직전 rebase)
+- 자료 우선순위: 태스크 문서 (다른 세션 TASK-XXX) / 커밋 메시지 / diff
+- 자료 한계 보고: (있으면 명시)
+- 해결 방향: <한 줄 요약>
+- 영향 파일: <목록>
+```
+
+### Step 6 — 머지 락 획득 + 락 안 재 rebase + 커밋 시퀀스
+
+#### 6-1. 머지 락 획득
+
+`bin/lib.js` `withMergeLock(projectId, fn, opts)` 호출. 내부 동작:
+
+```js
+// proper-lockfile
+await lockfile.lock(LOCK_FILE, {
+  stale: LOCK_TIMEOUT_MS,
+  retries: { retries: 5, factor: 1, minTimeout: 1000, maxTimeout: 1000 },
+});
+```
+
+재시도 모두 실패 시 → 사용자 보고 + 중단.
+
+#### 6-2. 락 안에서 rebase 재실행
+
+```sh
+git -C "$WT_PATH" rebase dev
+```
+
+락 외 rebase 이후 *다른 세션이 dev 머지했을 수 있음* — 락 안 rebase로 흡수.
+- 재충돌 발견 시 Step 4 에스컬레이션 재실행 + Step 5 문서 기록 재실행.
+
+#### 6-3. Phase 기능 커밋 (Dev Plan 각 Phase마다 1개 — task-close가 자동 생성)
+
+> **책임 영역**: taskery 정책상 `/task-dev` = *git 작업 X* (워크트리 코드만 수정). 본 단계가 *task-close가 uncommitted 변경분 정독 → task.md `## Dev Plan` Phase 진행 [x] 매핑 → Phase별 commit 자동 생성*하는 단일 진입점이다.
+
+자동 생성 절차:
+
+1. **uncommitted 변경분 정독**:
+   ```sh
+   git -C "$WT_PATH" status --porcelain
+   git -C "$WT_PATH" diff --name-only
    ```
-   - 대상: `.project/tasks/<vX.X>/<NNN>_<slug>.md` (단일 파일) 또는 `.project/tasks/<vX.X>/TASK-<NNN>_<slug>/task.md` (폴더 승격) — *task 본 파일 + 해당 NNN의 vX.X 공통 spec-diffs/<NNN>_<slug>_spec-diff.md / screenshots/<NNN>_*.png* 묶음.
-   - spec-diffs/screenshots는 *vX.X 공통* 위치 — 폴더 승격 시에도 task 폴더 안에 만들지 X (TASK_DOC_RULE §1.5 참조).
-4. **CHANGELOG 커밋 (해당 시)**:
-   - `.project/changelog/<YYYY-MM>.md` Edit (없으면 신규 Write):
-     ```markdown
-     # <YYYY-MM>
-
-     ## TASK-<NNN> — <제목>
-     - <Phase 1 요약>
-     - <Phase 2 요약>
-     - ...
-     ```
-   - 커밋:
-     ```
-     docs: [TASK-<NNN>] CHANGELOG 업데이트
-     ```
-   - 본 task에서 변경분 없으면 본 단계 *완전히 스킵* (빈 commit 금지).
+2. **task.md `## Dev Plan` 정독** — Phase별 `진행: [x]` + 파일 매핑 추출.
+3. **Phase ↔ 변경 파일 매핑**:
+   - 한 Phase가 단독 파일 영역이면 → Phase별 1 커밋.
+   - 같은 파일이 여러 Phase에 걸쳐 있으면 → *단일 통합 커밋 1개*로 묶음 (Phase 번호 표기는 *Phase X+Y*).
+   - 매핑 모호 / Dev Plan 본문 추적 불가 시 → 사용자 호출 + 결정 (자동 진행 X).
+- 메시지 형식 (GIT_RULE.md):
+  ```
+  {태그}: [TASK-<NNN>] Phase <N> - <작업 요약>
+
+  - <처리 내용 1>
+  - <처리 내용 2>
+  - 사유: <변경 이유>
+  ```
+- 태그: feature → `feat:`, bug → `fix:`, improvement → `improve:`, refactor → `refactor:`, docs/chore → `docs:`, 테스트 → `test:`
+
+> **GIT_RULE 풍부 메시지** — 본 메시지는 *충돌 해결 자료 2순위*로 쓰인다. 의도 한 줄 압축.
+
+> **자동 분리 로직 코드 구현**은 본 SKILL.md 영역 외 — 메인 세션이 본 절차를 따라 *수동/대화형* 진행. 향후 `bin/lib.js`에 `splitUncommittedByPhase(wtPath, taskMd)` 영역 별도 라운드.
+
+#### 6-4. flows/ 모듈 커밋 (해당 시)
+
+`$WT_PATH/.project/flows/<module>.md` 변경분 있으면 별도 커밋:
+```
+docs: [TASK-<NNN>] flows/<module>.md 갱신
+```
+
+- **`.gitignore` 미등록 케이스 한정** — 등록 케이스는 *워크트리 외부* 메인 워크트리 직접 수정 + `withMetaLock`.
+
+#### 6-5. task 파일 status → `closed` Edit
+
+closed-immutable.sh hook *허용* 영역 (status=closed 적용된 *후* 재수정이 차단).
+
+- **.gitignore 등록 케이스**: 메인 워크트리 task 문서를 `withMetaLock`으로 status=`closed` 갱신.
+- **.gitignore 미등록 케이스**: 워크트리 안 task 문서를 Edit.
+
+#### 6-6. 태스크 문서 커밋 (미등록 케이스 한정)
+
+```
+docs: [TASK-<NNN>] 태스크 문서 완료
+```
+
+- 대상: `$WT_PATH/.project/tasks/<vX.X>/<NNN>_<slug>.md` (단일) 또는 `.../TASK-<NNN>_<slug>/task.md` (폴더 승격) + spec-diffs / screenshots / mockup (vX.X 공통, TASK_DOC_RULE §1.5).
+- **등록 케이스**: Step 6-5에서 메인 워크트리 직접 수정으로 처리 — 별도 커밋 X (워크트리 머지에 포함 X).
+
+#### 6-7. CHANGELOG 커밋 (해당 시)
+
+`$MAIN_WT/.project/rules/CHANGELOG_RULE.md` 정독 후 형식 / 위치 준수.
 
-### Step 5 — dev 병합
+- 위치 분기:
+  - 미등록 — 워크트리 안 `$WT_PATH/.project/changelog/<YYYY-MM>.md` 갱신 + 커밋
+  - 등록 — `$MAIN_WT/.project/changelog/<YYYY-MM>.md` `withMetaLock` 갱신 (커밋 X)
+- 본 task에서 변경분 없으면 본 단계 *완전히 스킵* (빈 commit 금지).
 
-1. `git checkout dev` 실행.
-2. 일반 타입(feature/bug/improvement/refactor/docs/chore) → **`git merge --no-ff <작업 브랜치>` 강제** (fast-forward 절대 금지).
-   - `-m` 옵션 사용 금지 — 머지 커밋 메시지는 git 기본값 사용.
-3. plan/roadmap 임시 docs 브랜치 예외 — 단일 커밋이라 `--ff-only` 가능 (일반 흐름에서는 거의 발생 X).
-4. **작업 브랜치 자동 삭제 금지** — 사용자 명시 승인(*"브랜치 삭제해"*)이 있을 때만 `git branch -d`. 미승인 시 보존.
+### Step 7 — 메인 워크트리 uncommitted 검증 (머지 직전)
 
-### Step 6 — task 파일 status 전환
+```sh
+git -C "$MAIN_WT" status --porcelain
+```
+
+- 변경 있으면 → 사용자 호출 + 결정 (stash / 중단).
+- 등록 케이스에서 task 문서 직접 수정이 *.gitignore 차단으로 status에 안 잡힘* — 정상.
+
+### Step 8 — dev 머지
+
+```sh
+git -C "$MAIN_WT" merge --no-ff "$BRANCH"
+```
 
-헤더 status → `closed` Edit. 단 이 Edit은 closed-immutable.sh hook에 잡힐 수 있음 — task 파일 *마지막* 수정으로 적용한 후 별도 커밋 불필요(이미 Step 4-3에서 커밋함).
+- `-m` 옵션 금지 (git 기본 메시지).
+- 머지 커밋 해시 캡처: `MERGE_COMMIT=$(git -C "$MAIN_WT" rev-parse HEAD)`
 
-→ Edit이 Step 4-3 커밋 *전*에 일어나야 하므로 실제 흐름은:
+### Step 9 — 머지 락 해제
 
-**실제 순서 재정리**:
-1. Step 4-1: Phase 기능 커밋
-2. Step 4-2: flows/ 커밋 (해당 시)
-3. **task 파일 status를 `closed`로 Edit** (closed-immutable.sh hook 차단되지 X — 이 Edit은 *허용*. status가 closed가 *된 후 재수정*이 차단)
-4. Step 4-3: 태스크 문서 커밋 (status=closed 적용된 채로)
-5. Step 4-4: CHANGELOG 커밋
-6. Step 5: dev 병합
-7. Step 7: 마찰 신호 자체 감지 (`/log-friction` 발동 후보)
-8. Step 8: 결과 보고
+`withMergeLock` 콜백 종료 시 자동 release.
 
-### Step 7 — 마찰 신호 자체 감지 (`/log-friction` 발동 후보)
+### Step 10 — 마찰 신호 자체 감지 (`/log-friction` 발동 후보)
 
-본 task 진행 중 *마찰 신호* 누적 여부를 검사한다. 감지 시 `/log-friction` 등록을 사용자에게 제안.
+본 task 진행 중 *마찰 신호* 누적 여부를 검사. 감지 시 `/log-friction` 등록을 사용자에게 제안.
 
 검사 항목:
-- 동일 단계 재호출 ≥ 2회 (예: `/task-dev` Phase 동일 단계 반복 진입)
+- 동일 단계 재호출 ≥ 2회
 - 실패 반복 (검증 명령 FAIL 2회 이상 / 격리 세션 FAIL 후 재구현 반복)
-- 사용자 부정 반응 발화 누적 (불편·짜증·답답함 신호)
+- 사용자 부정 반응 발화 누적
+- **충돌 해결에서 *판단 불가 (4-c)* 1회 이상** — 멀티세션 자료 한계 신호
 
 분기:
-- **감지 신호 있음** → *"이번 task에서 X 부분이 마찰이었어 보여 — `/log-friction`으로 등록할까?"* 사용자 합의 받음. OK 시 `/log-friction` 자동 발동.
-- **감지 신호 없음** → prompt X (정상 close 진행).
+- 감지 신호 있음 → *"이번 task에서 X 부분이 마찰이었어 보여 — `/log-friction`으로 등록할까?"* OK 시 자동 발동.
+- 없음 → prompt X.
+
+### Step 11 — worktree remove 사전 검증
+
+```sh
+git -C "$WT_PATH" status --porcelain  # unstaged
+git -C "$WT_PATH" ls-files --others --exclude-standard  # 추적 X 파일
+```
+
+- 발견 시 사용자 호출 + 결정:
+  - 보존 → Step 12, 13 모두 건너뜀 (브랜치도 보존 — 정합)
+  - 삭제 → Step 12 진행
+  - 취소 → close 중단 (dev 머지는 이미 완료)
+
+### Step 12 — 워크트리 제거
 
-### Step 8 — 결과 보고
+```sh
+git -C "$MAIN_WT" worktree remove "$WT_PATH"
+```
+
+### Step 13 — 브랜치 자동 삭제 / 보존
+
+- **보존 키워드 감지** (`keep` / `--keep-branch` / `브랜치 남겨` / `브랜치 보존` / `브랜치 유지`) → 보존 + 워크트리도 보존 (Step 11~13 건너뛴 것과 정합).
+- **그 외** → `git -C "$MAIN_WT" branch -d "$BRANCH"`
+
+### Step 14 — 안전망 출력
+
+```
+삭제됨: $BRANCH
+복구: git -C "$MAIN_WT" branch $BRANCH $MERGE_COMMIT
+```
+
+### Step 15 — 결과 보고
 
 ```
 ✅ TASK-<NNN> closed
-- 작업 브랜치: <브랜치명>
+- 작업 브랜치: <BRANCH> (삭제 / 보존)
+- 워크트리: <WT_PATH> (제거 / 보존)
 - 커밋: Phase <N>개 + 태스크 문서 + (CHANGELOG)
-- dev 병합: --no-ff 완료
+- dev 병합: --no-ff 완료 ($MERGE_COMMIT)
+- 충돌 해결: <건수, 자료 한계 보고 있으면 포함>
 - 상태: tested → closed
-- 작업 브랜치 보존 (삭제하려면 "브랜치 삭제해" 명시)
-- 다음: 새 task 시작은 /task-init. 본 task에서 마찰 신호 감지된 경우 /log-friction 등록 제안
+- 다음: 새 task 시작은 /task-init. 마찰 신호 감지된 경우 /log-friction 등록 제안
 ```
 
 ## 도구 가이드
 
 - **Read**: GIT_RULE / task 파일 / CLAUDE.md 검증 명령 정독
-- **Bash**: git 명령 (`branch`, `checkout`, `add`, `commit`, `merge`) + 검증 명령 재실행. **유일하게 git 사용 허가된 스킬**
-- **Edit**: task 파일 status → `closed`, CHANGELOG 갱신
-- **Write**: CHANGELOG 신규 (없으면)
+- **Bash**: git 명령 (`branch`, `rebase`, `merge`, `worktree`) + 검증 명령 재실행. **유일하게 git 사용 허가된 스킬**
+- **Edit / Write**: task 파일 갱신, CHANGELOG (메타 위치는 `.gitignore` 케이스에 따라)
+- **bin/lib.js**: `withMergeLock` (머지 락) / `withMetaLock` (메타 파일 쓰기 락)
 
 ## 주의사항
 
-- **검증 명령 재실행 게이트** — `/task-dev` self-check / `/task-test` 격리 세션 PASS와 *별개로* 본 단계에서 한 번 더 실행. 환경 변화 / 부분 작업 / 메인 가정 등 잡는 안전망. 무리하게 게이트 우회 X.
-- **dev 직접 커밋 절대 X** — 작업 브랜치에서만. dev 브랜치에서 `git commit` 시도하면 git-guard.sh hook이 차단. hook이 0회 작동하도록 정상 흐름 준수.
-- **`--no-ff` 강제** — 머지 커밋 없으면 작업 브랜치 분기 정보 영구 손실. fast-forward 시도 절대 X.
-- **destructive 명령 사용자 승인 필수** — `git reset --hard` / `git push --force` / `git branch -D` / `git clean -fd` 사용자 명시 승인 없이 절대 실행 X. 충돌/오류 시 사용자에게 보고 + 승인 요청 의무.
-- **민감 정보 staging X** — `.env` / `credentials.json` / API key 등 staging 절대 X. `.gitignore`에 포함되어 있어도 한 번 더 점검.
-- **빈 commit 금지** — CHANGELOG 변경 없으면 4-4 단계 스킵. `--allow-empty` 사용 금지.
-- **작업 브랜치 자동 삭제 X** — 사용자 명시 승인 있을 때만. 머지 후 자동 삭제 룰 X (분기 정보 보존).
-- **branch -D 사용자 승인 필수** — `-d` (안전 삭제)는 머지 확인된 브랜치만 가능. `-D` (강제 삭제)는 사용자 명시 승인 필수.
-- **`-m` 옵션 머지 커밋에 사용 금지** — git 기본 메시지 사용 (GIT_RULE §병합 커밋).
+- **사용자 명시 호출 외 자체 진입 영구 금지** (stash FRICTION_LOG #6+10/#20) — task-close는 git 영역. 사용자가 *"X부터 Y까지"* 범위 명시했는데 Y가 close 이전 단계면 close 자체 진입 영구 X.
+- **검증 명령 재실행 게이트** — `/task-dev` self-check와 *별개*. 환경 변화 / 부분 작업 잡는 안전망.
+- **dev 직접 커밋 절대 X** — 워크트리에서만. dev에서 `git commit` 시도 시 git-guard.sh 차단.
+- **`--no-ff` 강제** — 머지 커밋 없으면 분기 정보 영구 손실.
+- **머지 락 직렬화** — 두 세션이 동시 머지 시도해도 한쪽씩 순차 진행. 락 외 rebase로 race 흡수 + 락 안 재 rebase로 다른 세션 머지 흡수.
+- **충돌 자체 해결 3단계** — 단순 자동 / 의미적 자료 / 판단 불가 사용자. 자료 한계 발견 시 *반드시 사용자에게 보고* (1순위 자료 부재 등).
+- **자료 한계 보고** — 충돌 분석 시 *2/3순위 fallback 사용했음*을 사용자에게 명시. 묵묵히 진행 X.
+- **destructive 명령 사용자 승인 필수** — `git reset --hard` / `git push --force` / `git branch -D` / `git clean -fd` 사용자 명시 승인 없이 절대 실행 X. (단 `/task-close` 자동 흐름 `git branch -d` + `worktree remove`는 §"작업 브랜치 삭제 정책 — 자동 삭제 면제 조항" 면제)
+- **민감 정보 staging X** — `.env` / `credentials.json` / API key 등 staging 절대 X.
+- **빈 commit 금지** — CHANGELOG 변경 없으면 6-7 단계 스킵. `--allow-empty` 사용 금지.
+- **`-m` 옵션 머지 커밋에 사용 금지** — git 기본 메시지 사용.
 
 ## 상태 전이
 
@@ -192,3 +341,11 @@ PASS 시 Step 3으로.
 | `tested` | `closed` |
 
 (검증 명령 FAIL + 사용자 *"고쳐"* → `developing`으로 되돌림. 본 스킬 자체는 거기서 중단.)
+
+## 멀티세션 정합
+
+- **머지 락** — `~/.taskery/<projectId>.merge.lock` 단일. 모든 세션 직렬화.
+- **task 문서 단일 진실 소스** — `.gitignore` 케이스에 따라 메인 워크트리 또는 워크트리. 다른 세션의 충돌 해결 자료 정독 시 *SSoT 조회 → 워크트리 경로 산출* (미등록 케이스) 또는 *메인 워크트리 절대 경로* (등록 케이스).
+- **워크트리 + 브랜치 자동 제거** — GIT_RULE.md "작업 브랜치 삭제 정책" 면제 조항 (taskery 한정). 보존 키워드 시 양쪽 보존.
+- **safety net** — Step 14 복구 명령 출력. 사용자가 잘못 삭제 인지 시 즉시 복구 가능.
+- **BACKLOG.md 무관** — `.project/tasks/<vX.X>/BACKLOG.md` 체크 마킹은 `/task-init` Step 7.5가 처리(`[ ]` → `[x]` + `- TASK: TASK-NNN`). `[x]` = *task로 옮김* 의미라 close 시점에 추가 마킹 X. 완료 추적은 `git log dev --grep 'BL-NNN'` + `npx @angar2/taskery status`.