@angar2/taskery 0.1.1 → 0.1.2

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

@@ -11,6 +11,23 @@ description: task 구현 — Dev Plan Phase 순서대로 코드 작성 + self-ch
 
 self-check 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션 참조 — 단일 진실 소스.
 
+## 멀티세션 메타 위치 (0.1.2+)
+
+본 스킬은 워크트리에서 호출된다. 메타(`.project/`, `CLAUDE.md`) 접근 시 **메인 워크트리 절대 경로** 우선.
+
+```sh
+MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+```
+
+`.gitignore` 케이스 분기:
+
+| 케이스 | task 문서 / Result 갱신 위치 | CLAUDE.md (검증 명령) |
+|--------|---------------------------|----------------------|
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` (`bin/lib.js` `withMetaLock`) | `$MAIN_WT/CLAUDE.md` |
+| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/CLAUDE.md` (CLAUDE.md는 단일 소스) |
+
+self-check 명령은 워크트리(`$WT_PATH`)에서 실행 — 코드 변경이 워크트리 안에 있으므로 검증 대상도 거기.
+
 ## 호출 시점
 
 - `/task-plan` 끝나고 기획 합의된 직후.
@@ -37,7 +54,10 @@ self-check 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션
    - `planned` → 신규 진행 (Step 2 status 전환).
    - `developing` → 이어가기 (Step 2 skip — 이미 developing).
    - 그 외 → 종료 + 안내.
-4. 프로젝트 루트 `CLAUDE.md` Read → *검증 명령* 섹션의 린트/타입체크/빌드/테스트 명령 추출. 이 명령들이 self-check 게이트의 단일 진실 소스.
+4. 프로젝트 루트 `CLAUDE.md` Read → 두 섹션 명령 추출:
+   - **`## 검증 명령`** (코드 상태 — 빌드/린트/타입체크): self-check 게이트의 단일 진실 소스 (Step 6).
+   - **`## 테스트 명령`** (테스트 실행 — 단위/통합/E2E): 구현 후 테스트 실행의 단일 진실 소스 (Step 6.5).
+   - stash FRICTION_LOG #25 반영 — 두 섹션 분리. self-check 게이트는 *코드 상태*만, 테스트는 *별도 단계*.
 
 ### Step 2 — status 전환 (planned → developing)
 
@@ -75,21 +95,44 @@ Dev Plan에 Phase 0(plan 문서 변경)이 있으면:
 | 단순 버그 수정 (로직 변경 없음) | 불필요 |
 | 스타일/포맷/설정 변경 | 불필요 |
 
-### Step 6 — self-check 게이트
+### Step 6 — self-check 게이트 (`## 검증 명령` — 코드 상태)
 
-Step 1에서 추출한 검증 명령을 *전부* 실행. 모두 PASS여야 `developed`로 전이 가능.
+`CLAUDE.md` `## 검증 명령` 섹션의 명령을 *전부* 실행. 모두 PASS여야 다음 단계 (Step 6.5 테스트 실행) 진입 가능. 테스트 명령은 본 게이트에서 실행 X.
 
 | 명령 | PASS 기준 |
 |------|---------|
 | 린트 (예: `npm run lint`) | exit 0 + 에러 0 |
 | 타입체크 (예: `npm run typecheck`) | exit 0 |
 | 빌드 (예: `npm run build`) | exit 0 |
-| 단위 테스트 (예: `npm test <범위>`) | 모든 케이스 PASS |
 
-**FAIL 시**:
-1. 메인이 자체 수정 시도 — 에러 메시지 분석 + 코드 수정 + 재실행.
-2. 같은 종류 fail이 3회 반복되면 사용자에게 보고 + 판단 요청 (*"이 에러가 풀리지 않아. 추가 정보 필요"*).
-3. 수정 + 재PASS 시까지 status `developing` 유지. PASS 못 받으면 `developed` 전환 X.
+**FAIL 시 — 추측 fix 반복 방지 룰 (stash FRICTION_LOG #15+16+18 반영)**:
+
+1. **1회 실패 시 자체 수정 시도** — 에러 메시지 + 스택 트레이스 *전체 정독*. 추측 X. 실제 로그 데이터 기반 fix.
+2. **2회 이상 실패 시 진단 로그 추가** — `console.log` / `print` / `logger.debug` 등 디버그 로그 추가 후 *실제 동작 데이터* 확보 후 root cause 확정. 추측 fix 반복 영구 금지.
+3. **동일 신고 재발 시 즉시 root cause 분석 모드** — 사용자 또는 자동화에서 *동일 에러 / 동일 신고* 재발 시 추측 fix 중단. `grep -rn <symbol>` 으로 *모든 사용처* 확인 + `git blame` 으로 *언제 추가된 줄* 확인 + 진단 로그 추가해 *실제 데이터* 추적. 동명 property / 함수 가능성 *항상 의심* (한 위치 fix 후 재발 시 다른 위치 우선 의심).
+4. 같은 종류 fail이 3회 반복되면 사용자에게 보고 + 판단 요청 (*"이 에러가 풀리지 않아. 진단 로그 결과: ... 추가 정보 필요"*).
+5. 수정 + 재PASS 시까지 status `developing` 유지. PASS 못 받으면 `developed` 전환 X.
+
+### Step 6.5 — 테스트 실행 (`## 테스트 명령` — 코드 정상성)
+
+stash FRICTION_LOG #14+19 / #25 반영 — 유닛 테스트는 본 단계에서 단일 시점 실행 (task-close / hook 영역 중복 제거).
+
+`CLAUDE.md` `## 테스트 명령` 섹션의 명령을 *전부* 실행. 모두 PASS여야 `developed`로 전이 가능.
+
+| 명령 | PASS 기준 |
+|------|---------|
+| 단위 테스트 (예: `npm test`) | 모든 케이스 PASS |
+| 통합 테스트 (있을 시) | 모든 케이스 PASS |
+| E2E 테스트 (있을 시) | 모든 시나리오 PASS |
+
+**신규 테스트 식별자 등장 확인 (stash FRICTION_LOG #19 반영)**:
+
+- 본 task에서 신규 테스트 추가되었으면 *단순 카운트 +N / 모든 PASS* 자체로 PASS 단정 X.
+- 신규 *테스트 식별자* (suite / class / function / describe 등) 가 테스트 runner 결과 로그에 *실제 등장*했는지 grep 직접 확인 (1 hit 이상).
+- 예: `grep -E "Suite \"<NewSuite>\"" test-output.log` → hit 1 이상.
+- 등장 안 하면 *Suite 미실행* (빌드 시스템 등록 누락 등) → FAIL 처리.
+
+**FAIL 시**: Step 6의 FAIL 룰 동일 적용 (추측 fix 반복 방지 / 진단 로그 / 동일 신고 재발 시 root cause).
 
 ### Step 7 — Result 섹션 진행 기록
 
@@ -136,6 +179,8 @@ Step 1에서 추출한 검증 명령을 *전부* 실행. 모두 PASS여야 `deve
 - **git 명령 절대 X** — 본 스킬은 코드만. `git commit` / `git push` / `git branch` 등 모두 `/task-close`에서. self-check fail 후 *재실행*도 git 무관.
 - **Phase 순서 건너뛰기 X** — Phase 1 끝나기 전 Phase 2 진행 X. 의존 관계 깨짐 + 디버깅 어려워짐.
 - **계획 외 스코프 확장 X** — Dev Plan에 없는 파일 다루기 전 사용자 confirm. *"이 부분 같이 작업해야 할 것 같은데 OK?"* 합의 후 진행.
+- **모호 발화 confirm 룰 (stash FRICTION_LOG #21+22 반영)** — 사용자 발화가 코드/문서/기능 영역에서 *복수 매칭* 가능할 때 자율 추정 영구 금지. 메인 *자체 안 1개* + *"X 의미 맞아?"* 한 줄 confirm 후 진행. 옵션 4개 늘어놓기 금지 (메인 판단 위임 회피 패턴). 예: 사용자 *"환경설정 아이콘"* 발화 → popover 톱니 / Settings 탭바 아이콘 둘 다 가능 → 어느 영역인지 한 줄 confirm 필수.
+- **디자인 산출 정독 의무 (stash FRICTION_LOG #14+19 / #12 일반화)** — task에 디자인 산출 (HTML 목업 / Figma / 디자인 파일 등) 있으면 메인이 *직접 Read* 후 구현. sub-agent 위임 금지 (요약만 받아 디자인 정합 깨짐). 구현 = 디자인 산출 기준 (역방향 X — 코드 편의로 디자인 어김 절대 X). 목업 위치 = `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`.
 - **self-check FAIL 시 `developed` 전환 X** — 무리하게 상태 갱신 금지. 메인 자체 수정 시도 → 안 되면 사용자에게 보고. *"잘 될 거야"* 가정 금지.
 - **로그 심기 잊지 X** — Dev Plan 작성 시 `[로그]` 항목 명시되어 있으면 *반드시* 실제 로그 코드 삽입. 격리 세션 / 운영 디버깅 모두 의존.
 - **Result 섹션 진행만** — 테스트 결과는 `/task-test`가 기록. 메인이 *"잘 됐을 거야"* 가정 작성 금지.

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

@@ -1,84 +1,193 @@
 ---
 name: task-init
-description: task 시작 — 6 섹션 빈 골격 + 헤더 5컬럼 (status=draft) task.md 생성
+description: task 시작 — 워크트리 분기 + 6 섹션 빈 골격 + 헤더 5컬럼 (status=draft) task.md 생성 (멀티세션 0.1.2+)
 ---
 
 # /task-init
 
 ## 개요
 
-새 task 시작 시 호출. `.project/tasks/<vX.X>/` 안에 *빈 골격* task.md 생성. 헤더 5컬럼 채우고 6 섹션은 placeholder만. 상태는 `draft`로 작성.
+새 task 시작 시 호출. **워크트리 분기 + task.md 빈 골격 작성**.
 
-본 스킬은 *생성만* 담당. Requirements / Scope / Dev Plan / Test Plan 본문은 다음 단계 `/task-plan`에서 채움.
+멀티세션 0.1.2+ — 본 스킬은 *작업 격리 워크트리*를 dev에서 분기 (`~/.taskery/worktrees/<projectId>/TASK-NNN_<출처>_<슬러그>/`) + 빈 골격 `task.md`를 작성한다. Requirements / Scope / Dev Plan / Test Plan 본문은 다음 단계 `/task-plan`에서 채움.
+
+> **호출 위치**: 메인 워크트리(dev 체크아웃 상태)에서 호출. 다른 워크트리에서 호출 시 → 사용자 호출 + 중단.
 
 ## 호출 시점
 
 - 새 task 시작 시 (사용자 발화: *"~~ 추가해줘"*, *"~~ 버그 고쳐"*, *"~~ 리팩터링"*).
 - 직전 대화로 작업 맥락 명확해진 직후.
+- 백로그 항목 진행 (사용자: *"BL-003 진행하자"*).
+- 로드맵 항목 진행 (사용자: *"로드맵 RM-002 시작"*).
 
 ## 입력 처리
 
-인자 = (선택) 주제 / 유형 / 규모 / 플랜. 예: `/task-init 로그인 기능` 또는 인자 없이 호출.
+인자 = (선택) 주제 / 유형 / 출처(BL-NNN, RM-NNN, DR) / 규모. 예: `/task-init 로그인 기능` / `/task-init BL-003` / 인자 없이 호출.
 
 두 분기:
 - **분기 1 (제안)**: 직전 맥락 명확 → 메인이 *"이렇게 task 만들까요?"* 제안 + 사용자 confirm.
 - **분기 2 (인터뷰)**: 직전 맥락 부족 → 한 번에 한 질문씩 인터뷰.
 
-**자동 추정 진행 X** — 사용자 confirm 또는 답 받기 전 파일 생성 금지.
+**자동 추정 진행 X** — 사용자 confirm 또는 답 받기 전 워크트리 생성 / 파일 생성 금지.
 
 ## 단계
 
-### Step 1 — active plan 버전 확인
-
-1. `.project/AGENT-GUIDE.md` Read → *활성 plan 버전* 추출 (예: `v1.0`).
+### Step 1 — 사전 검증 (멀티세션 안전망)
+
+`bin/lib.js` 유틸 활용 — 메인 워크트리 + dev 검증.
+
+1. **메인 워크트리 검출**:
+   ```sh
+   MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+   ```
+   - git ≥ 2.31 필요. 실패 시 *"git 버전 확인 — 2.31+ 필요"* 보고 + 중단.
+2. **현재 cwd가 메인 워크트리인지 확인**:
+   ```sh
+   CURRENT_WT=$(git rev-parse --show-toplevel)
+   [ "$CURRENT_WT" = "$MAIN_WT" ] || abort "메인 워크트리에서 호출해야 함 (현재: $CURRENT_WT)"
+   ```
+3. **dev 브랜치 존재 검증**:
+   ```sh
+   git -C "$MAIN_WT" rev-parse --verify dev || abort "dev 브랜치 부재. 사용자 결정 필요 (생성?)"
+   ```
+4. **메인 워크트리 = dev 검증**:
+   ```sh
+   CURRENT=$(git -C "$MAIN_WT" rev-parse --abbrev-ref HEAD)
+   [ "$CURRENT" = "dev" ] || abort "메인 워크트리가 dev 아님 (현재: $CURRENT). taskery 정책 위배"
+   ```
+5. **stale 의심 감지** (`npx @angar2/taskery status`로 위임 가능):
+   - 케이스 A (폴더 없는 워크트리): `git worktree prune` 제안 + 사용자 확인 후 실행
+   - 케이스 B (N일↑ 미커밋 브랜치): 알림만
+   - 케이스 C (워크트리 폴더 존재, N일↑ 비활성): 알림만
+   - 케이스 D (rebase 잔여 상태 — 워크트리에 `.git/rebase-apply` 또는 `.git/rebase-merge` 존재): 사용자 호출 + 선택 (continue / abort)
+   - N = `.taskery-manifest.json`의 `stale_days` (기본 30)
+
+위 검증 1개라도 실패 시 → 사용자 호출 + 중단.
+
+### Step 2 — active plan 버전 확인
+
+1. `$MAIN_WT/.project/AGENT-GUIDE.md` Read → *활성 plan 버전* 추출 (예: `v1.0`).
 2. AGENT-GUIDE.md 없거나 활성 버전 누락 시 → 사용자에게 *"활성 plan 버전이 없는데 `/plan-init` 먼저 실행할까요?"* 묻고 중단.
-3. `.project/plans/<vX.X>/` 디렉토리 존재 확인. 없으면 동일하게 `/plan-init` 안내 + 중단.
+3. `$MAIN_WT/.project/plans/<vX.X>/` 디렉토리 존재 확인. 없으면 동일하게 `/plan-init` 안내 + 중단.
 
-### Step 2 — 분기 판단 + 메타 수집
+### Step 3 — 분기 판단 + 메타 수집
 
 직전 대화 정독:
-- 작업 주제 / 유형 / 규모 추정 가능?
+- 작업 주제 / 유형 / 출처 / 규모 추정 가능?
   - **추정 가능** → 분기 1 (제안):
-    *"직전 맥락 보니 다음 task 만들까요? 주제: <X> / 유형: <Y> / 규모: <Z> / 플랜: <vX.X>. 어떠세요?"*
+    *"직전 맥락 보니 다음 task 만들까요? 주제: <X> / 유형: <Y> / 출처: <Z> / 규모: <W> / 플랜: <vX.X>. 어떠세요?"*
     사용자 답 — *"OK"* / *"규모는 large야"* / *"유형은 bug야"* 등 부분 수정 받음.
   - **추정 불가** → 분기 2 (인터뷰): 한 번에 한 질문씩.
     - Q1: *"무슨 작업인가요? (한 줄로)"*
     - Q2: *"유형? (feature / bug / improvement / refactor / docs / chore)"*
-    - Q3: *"규모? (micro / small / medium / large) — 잘 모르겠으면 추정 알려드림."*
-    - (필요 시) Q4: *"플랜 버전 `<vX.X>` 맞나요?"*
+    - Q3: *"출처? (백로그 BL-NNN / 로드맵 RM-NNN / 직접 요구사항 DR)"*
+    - Q4: *"규모? (micro / small / medium / large) — 잘 모르겠으면 추정 알려드림."*
+    - (필요 시) Q5: *"플랜 버전 `<vX.X>` 맞나요?"*
 
 수집 항목 (모두 확정되어야 진행):
-- 주제 (한국어 — kebab-slug 변환은 Step 4에서)
+- 주제 (한국어 — kebab-slug 변환은 Step 4)
 - 유형: `feature` / `bug` / `improvement` / `refactor` / `docs` / `chore`
+- 출처: `BL-NNN` / `RM-NNN` / `DR`
 - 규모: `micro` / `small` / `medium` / `large`
-- 플랜 버전: 활성 버전 그대로 (Step 1에서 가져온 값)
+- 플랜 버전: 활성 버전 그대로 (Step 2에서 가져온 값)
+
+### Step 4 — TASK 번호 결정 + 결정적 슬러그 + SSoT 안전망
+
+#### 4.1 다음 TASK-NNN 계산
+
+`bin/lib.js` `getNextTaskNumber(MAIN_WT)` 호출. 내부 동작:
+```sh
+# 진행중 (SSoT) — TASK-* 패턴 작업 브랜치 전체. `--no-merged dev` 미사용:
+# 워크트리 분기 직후 브랜치는 dev와 동일 commit이라 `--no-merged dev`가 *완전 머지 상태*로
+# 처리 → 빈 결과 → getNextTaskNumber 충돌. 브랜치 존재 자체가 SSoT.
+A=$(git -C "$MAIN_WT" branch --list \
+    'feature/*_TASK-*' 'bug/*_TASK-*' 'improve/*_TASK-*' \
+    'refactor/*_TASK-*' 'docs/*_TASK-*' 'chore/*_TASK-*' \
+    | grep -oE 'TASK-[0-9]+')
+# dev 머지 히스토리
+B=$(git -C "$MAIN_WT" log dev --grep='TASK-[0-9]\+' --extended-regexp --oneline \
+    | grep -oE 'TASK-[0-9]+')
+# 합집합 최대 + 1
+MAX=$( (echo "$A"; echo "$B") | sort -uV | tail -1 | sed 's/TASK-//')
+NEXT=$((MAX + 1))
+```
+- 3자리 zero-padded (`001`, `015`, `120`).
+- 합집합 비어 있으면 `001`.
+
+#### 4.2 메타 가져오기 (BL/RM)
+
+- BL: `$MAIN_WT/.project/tasks/<활성버전>/BACKLOG.md` Read → `BL-NNN` 블록 파싱 → `{ status, type, title, slug, summary, target, taskNums }` (활성 버전은 `AGENT-GUIDE.md`에서 검출. `bin/lib.js`의 `parseBacklogItem(mainWtPath, blId)` 호출 권장). 개요 / 대상 영역 → task.md §1 Requirements 초안에 자동 복사 (얕은 분석이 task 문서 시작점)
+- RM: `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md` Read → `RM-NNN` grep → 항목 메타 파싱
+- DR: 사용자 발화에서 주제 그대로
+
+#### 4.2.5 이미 `[x]` BL 재진행 케이스
+
+`parseBacklogItem` 결과 `status === 'checked'`이고 `taskNums` 비어 있지 않을 때:
+- 사용자 호출 + 결정: *"BL-NNN은 ${taskNums}로 이미 처리된 적 있어. 새 task로 다시 진행할까?"*
+- 사용자 OK → 새 TASK-NNN 진행. §7.5 (BL 확인 마킹) 단계에서 `- TASK:` 줄에 콤마로 추가 (덮어쓰기 X)
+- 사용자 X → task-init 중단
+
+#### 4.3 결정적 슬러그 산출
+
+- BL/RM: BACKLOG/ROADMAP에 박힌 슬러그 그대로 사용 (`parseBacklogItem` 결과의 `slug` 필드). task-init이 별도 변환 X — 재현성 보장
+- DR: 사용자 작명 또는 메시지에서 자동 산출 후 confirm
+- 한국어 → 영어 kebab-case. 짧고 명확하게 (3 단어 이내 권장).
+- 같은 항목이면 같은 슬러그 → 같은 브랜치명 → git이 동시 분기 자동 거부 (race 차단 1층).
+
+#### 4.4 SSoT 안전망 (race 차단 2층)
+
+```sh
+git -C "$MAIN_WT" branch --no-merged dev --list \
+  'feature/*_TASK-*' 'bug/*_TASK-*' 'improve/*_TASK-*' \
+  'refactor/*_TASK-*' 'docs/*_TASK-*' 'chore/*_TASK-*' \
+  | grep -E "_${SRC}_"
+```
+- BL-NNN/RM-NNN이 *진행중*에 있으면 → 중단 + 사용자 알림 (*"BL-003은 이미 X 세션에서 진행 중"*).
+- DR은 본 안전망 검사 X (별도 ID 없음).
+
+### Step 5 — 파일 vs 폴더 결정 + 브랜치명 산출
+
+1. 파일 vs 폴더 분기 (기존 룰 유지):
+   - **파일 default**: 단일 `NNN_<slug>.md`.
+   - **폴더 승격 조건**: (a) 규모 `large`, 또는 (b) 사용자 명시 *"폴더로 만들어줘"*, 또는 (c) task에 *추가 자료* 다수 예상.
+   - **spec-diffs / screenshots / mockup은 vX.X 공통** — 단일/폴더 모두 `.project/tasks/<vX.X>/{spec-diffs,screenshots,mockup}/`에 위치. (TASK_DOC_RULE §1.5)
+2. 브랜치명 산출 (멀티세션 형식):
+   ```
+   {타입}/{개발자}_TASK-NNN_{출처}_{슬러그}
+   예: feature/claude_TASK-007_BL-003_login-feature
+       bug/angar2_TASK-012_DR_mobile-form-refresh
+   ```
+   - **타입**: feature → `feature`, bug → `bug`, improvement → `improve`, refactor → `refactor`, docs → `docs`, chore → `chore`
+   - **개발자**: 메인 세션 = `claude`, 사용자 세션 = `angar2` 등
+3. 사용자에게 브랜치명 + 파일/폴더 confirm.
+
+### Step 6 — 워크트리 생성
+
+```sh
+PROJECT_ID=$(jq -r '.projectId' "$MAIN_WT/.taskery-manifest.json")
+WORKTREES_ROOT="$HOME/.taskery/worktrees/$PROJECT_ID"
+WT_PATH="$WORKTREES_ROOT/TASK-${NNN}_${SRC}_${SLUG}"
+mkdir -p "$WORKTREES_ROOT"
+git -C "$MAIN_WT" worktree add "$WT_PATH" -b "$BRANCH" dev
+```
 
-### Step 3 — TASK 번호 결정
+- git이 동일 브랜치명 자동 거부 (race 차단 1층).
+- 동시 충돌 시 *"브랜치 이미 존재 — 다른 세션이 같은 항목 진행 중"* 보고 + 중단.
 
-1. `ls .project/tasks/<vX.X>/` 실행 → 디렉토리 안 파일/폴더 목록 추출.
-2. 파일명 / 폴더명 패턴 검출:
-   - 파일: `NNN_<slug>.md` (예: `001_login-form.md`, `012_db-migration.md`)
-   - 폴더: `TASK-NNN_<slug>/` (예: `TASK-003_payment-flow/`)
-3. NNN 최대값 + 1 = 새 task 번호. 빈 디렉토리면 `001`.
-4. 3자리 zero-padded (`001`, `015`, `120`).
+### Step 7 — task 문서 위치 결정 + 빈 골격 작성
 
-### Step 4 — 파일 vs 폴더 결정 + slug 변환
+`.gitignore` 케이스 분기 — task 문서를 *메인 워크트리에 직접 작성* vs *워크트리 안에 작성*:
 
-1. 파일 vs 폴더 분기:
-   - **파일 default**: 단일 `NNN_<slug>.md` (예: `008_login-feature.md`).
-   - **폴더 승격 조건**: (a) 규모 `large`, 또는 (b) 사용자 명시 *"폴더로 만들어줘"*, 또는 (c) task에 *추가 자료*(서브 문서 / mockup / 디자인) 다수 예상.
-     → `TASK-NNN_<slug>/task.md` 생성. 추가 자료는 *task 폴더 안에 자유롭게* 위치.
-   - **`spec-diffs/` + `screenshots/`는 *vX.X 공통* 사용**: 단일 파일이든 폴더 승격이든 `.project/tasks/<vX.X>/{spec-diffs,screenshots}/`에 위치 (파일명에 NNN prefix로 task 식별 — `<NNN>_<slug>_spec-diff.md`). task 폴더 안에 spec-diffs/screenshots 생성하지 않음.
-   - 위 디렉토리는 `/plan-init` Step 5가 vX.X 만들 때 함께 mkdir됨. `/task-init`은 디렉토리 가정만, 직접 생성 X.
-2. slug 변환 — 한국어 → 영어 kebab-case:
-   - 짧고 명확하게 (3 단어 이내 권장).
-   - 소문자 + 하이픈만. 예: *"로그인 기능 추가"* → `login-feature`, *"모바일 사파리 폼 새로고침 버그"* → `mobile-safari-form-refresh`.
-3. 사용자에게 슬러그 confirm (선택):
-   *"파일명: `<NNN>_<slug>.md` 어떠세요? (수정 원하면 말씀)"*
+```sh
+git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
+```
 
-### Step 5 — 빈 골격 작성
+| 결과 | 케이스 | 작성 위치 |
+|------|--------|----------|
+| exit 0 | **등록됨** (퍼블릭 리포 default) | **메인 워크트리** (`$MAIN_WT/.project/tasks/<vX.X>/`) — proper-lockfile로 안전 쓰기. 멀티세션 공유 단일 소스. dev untracked (git 자동 무시) |
+| exit 1 | **미등록** | **워크트리 안** (`$WT_PATH/.project/tasks/<vX.X>/`) — 워크트리 커밋 + 머지 시 dev에 반영 |
 
-`# TASK-<NNN> — <한국어 제목>` + 헤더 5컬럼 + 6 섹션 placeholder. 양식은 `template/.project/rules/TASK_DOC_RULE.md` §1.3 참조.
+빈 골격 형식 (TASK_DOC_RULE §1.3 참조):
 
 ```markdown
 # TASK-<NNN> — <한국어 제목>
@@ -109,35 +218,66 @@ description: task 시작 — 6 섹션 빈 골격 + 헤더 5컬럼 (status=draft)
 ```
 
 - 6 섹션 placeholder는 *빈 헤딩 + 한 줄 안내*. 구체 내용 X.
-- 폴더 승격 시 `TASK-<NNN>_<slug>/task.md`로 동일 본문 작성. spec-diffs/screenshots는 vX.X 공통(`.project/tasks/<vX.X>/{spec-diffs,screenshots}/` — `/plan-init` Step 5가 mkdir)을 그대로 사용. task 폴더 안에 spec-diffs/screenshots 별도 생성 X.
+- 폴더 승격 시 `TASK-<NNN>_<slug>/task.md`로 동일 본문 작성.
+
+### Step 7.5 — BL 출처 BACKLOG.md 확인 마킹 (BL일 때만)
+
+§4 출처 결정에서 *BL*이 선택된 경우만 실행. RM/DR은 skip.
+
+`bin/lib.js`의 `markBacklogChecked(mainWtPath, blId, taskNum)` 호출.
 
-### Step 6 — 결과 보고
+내부 흐름 (`withMetaLock` 안에서 원자성 보장):
+1. 첫 줄 패턴 `- [ ] **BL-NNN**` → `- [x] **BL-NNN**`로 4번째 글자(체크박스) 치환
+2. 같은 BL 블록 끝 (다음 `- ` 헤드 또는 파일 끝 직전, 빈 줄 건너뛴 위치) 에 `  - TASK: TASK-NNN` 한 줄 append
+3. 이미 `  - TASK:` 줄 있으면 → 콤마로 추가 (`TASK-007, TASK-012`. 덮어쓰기 X)
+
+`[x]` 의미: *"이 항목은 task로 옮겼다"*. **dev 머지 완료 의미 X**. 완료 추적은 `git log dev --grep 'BL-NNN'` + 브랜치명 + `npx @angar2/taskery status`.
+
+> §4.2.5 (이미 `[x]` BL 재진행 케이스)에서 사용자 OK 받은 경우만 본 단계 진입. 사용자 X로 중단된 경우 본 Step 7.5도 skip.
+
+### Step 8 — 결과 보고
 
 ```
 ✅ TASK-<NNN> 생성 완료
-- 파일: .project/tasks/<vX.X>/<NNN>_<slug>.md (또는 폴더 승격 시 경로)
+- 워크트리: <WT_PATH>
+- 브랜치: <BRANCH>
+- task 문서: <TASK_DOC_PATH> (메인 워크트리 / 워크트리 안 — 위 케이스에 따라)
 - 헤더: <생성일> / <vX.X> / <유형> / <규모> / draft
-- 다음: /task-plan TASK-<NNN> 으로 기획 채우기
+- BL 마킹: BL-<NNN> [x] (BL 출처 시. RM/DR이면 생략)
+- 다음: 워크트리 폴더에서 새 세션 열기 → /task-plan TASK-<NNN> 으로 기획 채우기
 ```
 
 ## 도구 가이드
 
-- **Read**: `.project/AGENT-GUIDE.md` (활성 버전 확인)
-- **Bash**: `ls .project/tasks/<vX.X>/` (NNN 결정), `mkdir -p .project/tasks/<vX.X>/TASK-<NNN>_<slug>` (폴더 승격 시 — task 폴더 자체만, spec-diffs/screenshots는 vX.X 공통 사용)
-- **Write**: 새 task.md 생성
+- **Bash**: 메인 워크트리 검출 / 사전 검증 / `git worktree add` / SSoT 조회 / TASK-NNN 계산
+- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` / `$MAIN_WT/.project/tasks/<활성버전>/BACKLOG.md` / `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md`
+- **Write**: task.md 빈 골격 작성 (위치는 .gitignore 케이스에 따라)
 - **AskUserQuestion**: 분기 2 인터뷰 (한 번에 한 질문)
 
 ## 주의사항
 
-- **본문 채우기 금지** — 본 스킬은 *빈 골격 생성만*. Requirements / Scope / Dev Plan / Test Plan 본문은 *반드시* `/task-plan`에서. 미리 채우면 task 의도가 흐트러져 다음 단계 인터뷰 흐름이 깨짐.
-- **자동 추정 진행 X** — 직전 맥락 명확해도 *제안 + 사용자 OK* 거친 후 파일 생성. 맥락 부족 시 인터뷰. 빠뜨린 메타(유형/규모) 채로 작성 금지.
-- **상태는 `draft` 고정** — `/task-init` 끝의 상태는 `draft` 외 작성 금지. 다음 상태(`planned`)는 `/task-plan` 끝에 갱신.
-- **NNN 충돌 회피** — `ls` 결과 정확히 파싱. 파일/폴더 둘 다 검사 (폴더 승격 task의 NNN도 같은 시퀀스).
-- **slug 한국어 잔존 X** — 영어 kebab-case로 변환. *"로그인-기능"* 같은 한글 슬러그 금지.
-- **헤더 5컬럼 모두 채움** — *"미정"* placeholder 작성 금지. 메타 부족하면 사용자에게 묻기.
+- **워크트리 생성 + task 문서 작성만 담당** — 본문 채우기 금지. Requirements / Scope / Dev Plan / Test Plan 본문은 *반드시* `/task-plan`에서.
+- **단계 경계 — 허용/금지 명시 (stash FRICTION_LOG #11 반영)**:
+  - **허용 (화이트리스트)**: `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md` §4(다음 작업 영역) 확인 / SSoT 조회 / TASK-NNN 계산 / 빈 골격 Write
+  - **금지 (블랙리스트)**: ARCHITECTURE.md / API-SPEC.md / FEATURES.md 등 9 기획 문서 본문 Read / 도메인 코드 Read · Grep / 기존 task 본문 Read
+  - 본문 정보 수집은 *다음 단계 `/task-plan`*에서 수행.
+- **자동 추정 진행 X** — 직전 맥락 명확해도 *제안 + 사용자 OK* 거친 후 워크트리/파일 생성.
+- **상태는 `draft` 고정** — `/task-init` 끝의 상태는 `draft` 외 작성 금지.
+- **NNN 충돌 회피** — SSoT 조회로 진행중 + dev 머지 히스토리 합집합 확인.
+- **slug 한국어 잔존 X** — 영어 kebab-case로 변환.
+- **헤더 5컬럼 모두 채움** — *"미정"* placeholder 작성 금지.
+- **메인 워크트리 검출 실패 시 즉시 중단** — git 버전 / 정책 위배 / dev 부재 등 안전망. 묵묵히 진행 X.
+- **race 발생 시 사용자 호출** — `git worktree add` 실패(같은 브랜치명) → SSoT 재조회 + 사용자에게 *"X 세션이 같은 항목 진행 중"* 알림.
 
 ## 상태 전이
 
 | 진입 시 | 종료 시 |
 |--------|--------|
 | (없음 — 신규 생성) | `draft` |
+
+## 멀티세션 정합
+
+- **다른 세션 진행중 태스크** = SSoT (git branch --no-merged) 단일 진실 소스
+- **워크트리 정리**: 본 스킬은 *생성*만. 제거는 `/task-close` 또는 `npx @angar2/taskery prune`
+- **머지 락**: 본 스킬은 머지 안 함 — 락 불필요
+- **충돌 자체 해결**: 본 스킬 영역 X — `/task-close`에서 처리

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

@@ -11,6 +11,23 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 
 리뷰는 *대화로 OK* 자동 전이로 단순화 — 별도 리뷰 단계 없음.
 
+## 멀티세션 메타 위치 (0.1.2+)
+
+본 스킬은 워크트리에서 호출된다. 메타(`.project/`, `CLAUDE.md`) 접근 시 **메인 워크트리 절대 경로** 우선 — *task 문서 단일 진실 소스* 유지.
+
+```sh
+MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+```
+
+`.gitignore` 케이스 분기:
+
+| 케이스 | task 문서 위치 | 9 기획 문서 위치 | 동시 쓰기 |
+|--------|--------------|----------------|----------|
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` | `$MAIN_WT/.project/plans/<vX.X>/...` | `withMetaLock` (`bin/lib.js`) |
+| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/.project/plans/<vX.X>/...` (plan 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
+
+본문 모든 `.project/...` 경로는 *위 분기에 따라* 적용. spec-diff / mockup / screenshots는 task 문서와 같은 위치.
+
 ## 호출 시점
 
 - `/task-init`로 만든 빈 골격 task에 기획 채울 때.
@@ -120,33 +137,108 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 ### Phase 2 — ...
 ```
 
-### Step 5 — Test Plan (자유 형식 + 가이드라인)
+### Step 4.5 — HTML 목업 프로세스 (UX/UI 구현 task 한정 — stash FRICTION_LOG #14+19 반영)
 
-양식 강제 X. *작업에 맞게 자유롭게* 작성. 단 가이드라인 준수 (TASK_DOC_RULE §2.5):
+본 task가 UX/UI 구현 포함하면 *시각 영역 사전 정합* + *task-test 시 USER 검수 기준 확보*용 HTML 목업 생성.
 
-- **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
-- **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
-- **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+#### 1. UX/UI 구현 task 판단
+
+Step 2 Requirements 인터뷰 결과로 본 task가 *UX/UI 구현 (페이지/컴포넌트 신규 / 시각 변경 / 인터랙션 신규)* 포함 여부 판단.
+
+- UX/UI 포함 → 2~5 진행
+- 미포함 (백엔드 / CLI / 인프라 등) → 본 Step 패스, Step 5로 직진
+
+#### 2. 목업 confirm
+
+사용자에게 한 줄 질문:
+*"이 task UX/UI 구현 포함되어 있어. HTML 목업 만들까? 구현 정확도 + 사용자 사전 시각 확인 + task-test 검수 기준 확보 효과."*
+
+- 사용자 *"OK"* → 3 진행
+- 사용자 *"NO"* → 본 Step 패스 (목업 없이 진행)
+
+#### 3. 목업 생성 + 사용자 승인
+
+1. 메인이 HTML 목업 생성 — 정적 HTML/CSS (외부 라이브러리 X, 단일 파일 안 inline style + 필요 시 vanilla JS):
+   - 시각 영역 (레이아웃 / 색상 / 간격 / 타이포 / 호버 효과)
+   - 인터랙션 (가능한 범위 — 클릭 / 호버 시뮬)
+2. 사용자에게 *"브라우저로 `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
+3. 사용자 ✓ → 승인 완료, 4 진행. ✗ → 메인이 수정 후 재승인 요청.
+
+#### 4. 파일 위치 / 네이밍
+
+- 위치: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+  - 예: `001_login-form.md` → `001_login-form-mockup.html`
+- **task 1개 = 목업 1개**. multi-file 예외 영구 X. 복잡해도 한 파일 안 섹션 분리 (`<section id="popover">` `<section id="settings">` 등).
+
+#### 5. Test Plan 연결
+
+승인된 목업 = task-test의 *시각 영역 USER 검수 기준*. Step 5 Test Plan 작성 시 시각 시나리오에 `[USER]` 분류 + 목업 경로 참조 명시.
 
-자유 형식 예 (체크리스트 / 시나리오 / 명령 나열):
+---
+
+### Step 5 — Test Plan (실질 동작 시나리오 — stash FRICTION_LOG #14+19 / #25 반영)
+
+#### 본질
+
+Test Plan = *본 task에서 구현한 요구사항이 정상 동작하는지* 검증 시나리오. **유닛 테스트 X** (유닛 테스트는 task-dev Step 6.5에서 단일 시점 실행 — *코드 정상성* 영역, 본 Test Plan과 직교).
+
+검증 대상:
+- 기능 동작: 사용자 입력 → 기대 결과 / API 호출 → 응답 / 데이터 처리 → 상태 변화
+- UX/UI 동작: 클릭 → 결과 / 호버 → 상태 / 드래그 → 위치 변경
+- UX/UI 시각: 레이아웃 / 색상 / 간격 / 호버 효과 (목업 기준)
+- 백엔드 동작: 시스템 호출 → 외부 응답 / 사이드 이펙트 / 에러 처리
+
+#### 실질 테스트 방식 카탈로그
+
+각 시나리오마다 아래 방식 중 적합한 1개 이상 선택:
+
+| 방식 | 적용 영역 | 설명 |
+|------|----------|------|
+| 수동 검수 | UI / UX / 인터랙션 | 사용자가 실제 앱·환경에서 직접 조작·확인 |
+| 시나리오 스크립트 실행 | 백엔드 / 통합 흐름 | end-to-end script (bash / node 등) 일련의 명령 자동 실행 |
+| API/엔드포인트 호출 | 백엔드 / 외부 인터페이스 | 실제 호출 + 응답·상태 코드·결과 데이터 확인 |
+| 입출력 비교 | 함수 / 변환 / 처리 | 입력 → 출력 비교 (snapshot / golden file) |
+| 사이드 이펙트 확인 | DB / 파일 / 로그 | 시나리오 실행 후 상태 직접 조회 |
+| 회귀 시나리오 | 기존 기능 영향 | 직전 동작하던 시나리오 재실행 |
+| E2E 자동화 도구 | UI 자동화 (도구 있을 시) | Playwright / Cypress / XCTest UI Test 등 — 가능하면 자동화, 안 되면 수동 검수 |
+
+#### UX/UI 영역 분리 + 검증 방식 매트릭스 (UX/UI 구현 task 한정)
+
+| 영역 | 자동화 가능 시 | 자동화 불가 시 |
+|------|---------------|---------------|
+| 동작 (클릭/호버/드래그/입력 → 결과) | `[AUTO]` E2E 자동화 시나리오 스크립트 | `[USER]` 체크리스트 |
+| 시각 (레이아웃/색상/간격/호버 효과 강도) | (자동 비교 의미 없음 — 픽셀 단위 변화 + 주관 판단 영역) | `[USER]` 체크리스트 + 목업 기준 참조 |
+
+#### 시나리오 형식
 
 ```markdown
 ## Test Plan
 
-1. `npm run dev` → http://localhost:3000/<경로> 접속.
-2. <시나리오 1>:
-   - 기대: <응답/표시>
-3. <시나리오 2>:
-   - 기대: ...
-
-검증 명령:
-- `npm run lint` PASS
-- `npm run typecheck` PASS
-- `npm run build` PASS
-- `npm test <관련 파일>` PASS
+| # | 시나리오 | 분류 | 방식 | PASS 기준 |
+|---|---------|------|------|----------|
+| 1 | <한 줄 설명> | [AUTO] / [USER] | <카탈로그 방식> | <명확한 기대값> |
+| 2 | ... | ... | ... | ... |
+
+(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
 ```
 
-검증 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션을 참조해 그대로 인용.
+#### 시각 영역 fix 사이클 사전 예고 (stash FRICTION_LOG #14 반영)
+
+시각 영역 시나리오가 1개 이상 있으면 Test Plan 끝에 명시:
+
+> 시각 영역 항목 N개 — 한 사이클로 100% 일치 보장 X. fix 사이클 1~2회 예상. ✗ 발견 시 정상 (사용자 부정 반응 누적 방지 — 기대치 사전 정렬).
+
+#### 가이드라인 (TASK_DOC_RULE §2.5 정합)
+
+- **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
+- **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
+- **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+
+#### 검증/테스트 명령 참조
+
+`/task-test` 격리 세션은 프로젝트 루트 `CLAUDE.md`의 두 섹션을 자동 참조 — Test Plan에 재인용 불필요:
+- `## 검증 명령` (코드 상태 — 빌드/린트/타입체크)
+- `## 테스트 명령` (테스트 실행 — 단위/통합/E2E)
 
 ### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
 
@@ -197,10 +289,14 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 
 - **본문 영역만 작성** — 헤더 5컬럼 중 *상태*만 갱신(`draft` → `planned`). 생성일/플랜/유형/규모는 `/task-init`에서 작성된 값 유지. 단 Step 4에서 *규모가 명백히 잘못 추정*된 게 드러나면 사용자 confirm 후 갱신 OK (예: medium 추정했는데 Phase 8개 나옴 → large 갱신 + 분리 검토).
 - **Phase 선제적 일괄 작성 금지** — small task에 medium 분량 Phase 작성하는 함정 회피. 명확한 것만 작성하고 진행 중 추가.
+- **Test Plan = 실질 동작 시나리오 (유닛 테스트 X)** — Test Plan은 *요구사항이 정상 동작하는지* 검증. 유닛 테스트는 task-dev Step 6.5에서 단일 시점 실행 (코드 정상성 영역, Test Plan과 직교).
 - **Test Plan 자기완결적** — 격리 세션이 *task.md만 보고* 수행 가능해야. 메인의 plan/dev 컨텍스트 *"위 Phase에서 만든 X"* 같은 표현 금지. 코드/동작/명령만 명시.
 - ***"잘 될 거야"* 가정 금지** — Test Plan에 메인 가정 작성 금지. 코드와 동작만 신뢰.
 - **합의 없이 status 전환 X** — 사용자 OK 받기 전 `planned` 작성 금지. 합의가 *대화로 OK = 자동 전이* 룰의 핵심.
 - **과규모(large) 시 분리 제안** — Phase 8개 초과 또는 성격 다른 기능 혼재 시 task 분리 권장. 사용자에게 *"A/B로 쪼갤까요?"* 제안.
+- **UX/UI task — 목업 프로세스 누락 X** — UX/UI 구현 task는 Step 4.5 목업 confirm 필수. 사용자 *NO* 응답이면 패스, *OK*면 생성 + 승인. 목업 누락 시 task-test 시각 USER 시나리오 기준 부재.
+- **디자인 산출 정독 의무 (stash FRICTION_LOG #14+19 / #12 일반화)** — task에 디자인 산출 (HTML 목업 / Figma / 디자인 파일) 있으면 메인이 *직접 Read* 후 Test Plan 작성. sub-agent 위임 금지 (요약만 받아 시각 정합 깨짐).
+- **모호 발화 confirm 룰 (stash FRICTION_LOG #21+22 반영)** — 사용자 발화가 복수 매칭 가능할 때 자율 추정 금지. 메인 *자체 안 1개* + *"X 의미 맞아?"* 한 줄 confirm. 옵션 4개 늘어놓기 금지.
 
 ## 상태 전이