@angar2/taskery 0.1.1 → 0.1.3

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> 으로 기획 채우기 (워크트리 폴더에서 새 세션 열어 진행 / 메인 세션 그대로 진행 / 메인이 서브 세션 spawn 등 운영 모델 자유)
 ```
 
 ## 도구 가이드
 
-- **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+)
+
+본 스킬은 워크트리에서 호출되는 게 default (멀티세션 — 각 워크트리 = 독립 세션). 다만 호출 위치 자유 — 메인 cwd / 서브 세션 호출 등 다른 운영 모델에서도 cwd 무관 동작. 메타(`.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,137 @@ 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 반영)
+
+본 task가 UX/UI 구현 포함하면 *시각 영역 사전 정합* + *task-test 시 USER 검수 기준 확보*용 HTML 목업 생성.
+
+#### 1. UX/UI 구현 task 판단
+
+Step 2 Requirements 인터뷰 결과로 본 task가 *UX/UI 구현 (페이지/컴포넌트 신규 / 시각 변경 / 인터랙션 신규)* 포함 여부 판단.
+
+- UX/UI 포함 → 2~5 진행
+- 미포함 (백엔드 / CLI / 인프라 등) → 본 Step 패스, Step 5로 직진
+
+#### 2. 목업 confirm
+
+**예외 없이 사용자에게 발화 강제** — UX/UI 포함 판단=O이면 본 confirm 질문은 *반드시* 발화. 메인의 효용 판단(*"이 케이스는 목업 효용 낮음"* / *"SF Symbol은 HTML 재현 X"* 등)으로 confirm 단계 자체를 건너뛰는 행위 영구 금지. 효용 판단은 질문에 *곁들이는 의견*으로만 표현 가능 (생략 결정 대체 X — 목업 제작 여부는 *사용자 검수 방식 선택권*이라 *개발 자율 판단* 영역 X).
+
+근거: stash FRICTION_LOG 2026-06-01 — UX/UI 구현 task인데 메인이 *목업 효용 낮음* 자체 판단으로 Step 4.5 confirm 자체를 생략한 마찰.
+
+사용자에게 한 줄 질문:
+*"이 task UX/UI 구현 포함되어 있어. HTML 목업 만들까? 구현 정확도 + 사용자 사전 시각 확인 + task-test 검수 기준 확보 효과."*
+
+(효용 한계 의견 곁들이기 — 해당 시): *"단, <기술 한계 — 예: SF Symbol 아이콘은 HTML 재현 X> 영역은 목업 효용 제한적."* — 의견 표현만 가능, 생략 결정 대체 X.
+
+- 사용자 *"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]` 분류 + 목업 경로 참조 명시.
+
+---
 
-양식 강제 X. *작업에 맞게 자유롭게* 작성. 단 가이드라인 준수 (TASK_DOC_RULE §2.5):
+### 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
+
+| # | 시나리오 | 분류 | 방식 | PASS 기준 |
+|---|---------|------|------|----------|
+| 1 | <한 줄 설명> | [AUTO] / [USER] | <카탈로그 방식> | <명확한 기대값> |
+| 2 | ... | ... | ... | ... |
+
+(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+```
+
+#### 시각 영역 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**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+- **grep/Read-only 존재 확인 시나리오 = 보조용** (stash FRICTION_LOG 2026-06-01 반영) — 구현 코드의 존재 여부를 grep/Read로 재확인하는 시나리오는 *동어반복*. PASS 카운트에서 제외하거나 실동작 시나리오의 *보조*로만 사용. 단독 검증 가치 X.
+- **요구사항당 end-to-end 1개 이상 강제** — Requirements 각 항목이 *사용자 관점에서 실제 작동하는지* 검증하는 end-to-end 실동작 시나리오 최소 1개 보장. 산출물 실행 → 결과 확인 형태.
+- **무거운 검증 회피 영구 금지** — 부담(빌드 수 분+ / 외부 의존 / 환경 설정) 이유로 실동작 시나리오를 grep 동어반복으로 대체 X. 최소 1회는 실제 산출물로 확인. 부담은 *fix 사이클 1~2회 예상* 같은 사전 예고로 처리 (생략 사유 X).
+
+#### 요구사항 ↔ 시나리오 커버리지 점검 (필수 — stash FRICTION_LOG 2026-06-01 반영)
+
+Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋 안 함"* 같은 요구사항이 시나리오에서 통째로 빠지는 누락 차단용.
 
-자유 형식 예 (체크리스트 / 시나리오 / 명령 나열):
+1. Requirements 섹션 합의 항목 전체를 *매트릭스*로 펼침.
+2. 각 요구사항 항목당 *최소 1개 시나리오 커버* 확인.
+3. 미커버 항목 발견 시 → 시나리오 보강 후 재점검.
+
+형식 (Test Plan 끝에 첨부):
 
 ```markdown
-## Test Plan
+### Requirements ↔ 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
+| 요구사항 | 커버 시나리오 # |
+|---------|----------------|
+| <Req 1 한 줄> | #1, #3 |
+| <Req 2 한 줄> | #2 (end-to-end) |
+| <Req 3 한 줄> | #5 |
 ```
 
-검증 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션을 참조해 그대로 인용.
+#### 검증/테스트 명령 참조
+
+`/task-test` 격리 세션은 프로젝트 루트 `CLAUDE.md`의 두 섹션을 자동 참조 — Test Plan에 재인용 불필요:
+- `## 검증 명령` (코드 상태 — 빌드/린트/타입체크)
+- `## 테스트 명령` (테스트 실행 — 단위/통합/E2E)
 
 ### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
 
@@ -197,10 +318,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개 늘어놓기 금지.
 
 ## 상태 전이