@angar2/taskery 0.2.0 → 0.3.0

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

@@ -66,15 +66,15 @@ LOCK_FILE="$HOME/.taskery/${PROJECT_ID}.merge.lock"
    git -C "$WT_PATH" status --porcelain
    ```
    - 결과 *있음* = 정상 흐름 (taskery 정책: `/task-dev` = *git 작업 X*). 본 변경분은 Step 6-3에서 *task-close가 자동 Phase 커밋 생성*으로 처리.
-   - 결과 *없음* = 변경분 0건 → Step 2 검증만 수행 후 Step 6-3 자동 커밋 단계 자연 스킵 (빈 커밋 X).
+   - 결과 *없음* = 변경분 0건 → Step 2 검증만 수행 후 Step 6-3 자동 커밋 단계 스킵. **단 6-7까지 거쳐도 워크트리 브랜치가 dev보다 앞선 커밋이 0개면 Step 6-8에서 추적 마커 빈커밋 1개 생성** (`.project` gitignore + docs/분석 전용 task → 채번 보존).
    - **차단 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>/...` (워크트리 안)
+     - exit 0 (등록됨): `$MAIN_WT/.project/tasks/<NNN_slug>/...` (단일 소스)
+     - exit 1 (미등록): `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안)
    - 상태 = `tested` 검증. 그 외면 종료 (단 알려진 결함 *"OK 마무리"*는 status=tested로 명시되어 있어야 함).
    - GIT_RULE Read 우선순위:
      - `$MAIN_WT/.project/rules/GIT_RULE.md` (프로젝트별 — 우선)
@@ -123,12 +123,12 @@ git -C "$WT_PATH" rebase dev
 
 | 순위 | 자료 | 위치 |
 |------|------|------|
-| 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 등) |
+| 1 | 태스크 문서 + 제품/plan 문서 (양쪽 정독 후 의도 종합) | 태스크: `$MAIN_WT/.project/tasks/<NNN_slug>/...` (등록 케이스) / `~/.taskery/worktrees/<projectId>/TASK-...` 다른 워크트리 (미등록 케이스, SSoT 조회로 경로 산출). 제품 관통 문서(FEATURES / ARCHITECTURE / TECH-STACK / DATA-MODEL / API-SPEC 등) = `$MAIN_WT/.project/<doc>.md` (루트 평평). plan 로컬(ROADMAP / PLAN) = `$MAIN_WT/.project/plans/<NNN_slug>/` |
 | 2 | 커밋 메시지 | `git log dev --grep` (GIT_RULE 풍부 메시지) |
 | 3 | diff | 변경 코드 자체 |
 
 - 1순위 부재 시 2/3순위 자동 fallback + 사용자에게 *자료 한계* 보고
-- 태스크 문서 = 본 task의 *세부 의도* / plan 문서 = *전체 의도* (Stage 순 / 의존 그래프 / 의도된 위치 분리). 충돌 영역의 *그림 전체*는 plan 문서가 더 명확한 경우 많음 (Stage 순서로 *먼저 머지된 쪽 다음 줄에 추가* 등)
+- 태스크 문서 = 본 task의 *세부 의도* / 제품·plan 문서 = *전체 의도* (Stage 순 / 의존 그래프 / 의도된 위치 분리). 충돌 영역의 *그림 전체*는 제품 문서(FEATURES/ARCHITECTURE)·ROADMAP이 더 명확한 경우 많음 (Stage 순서로 *먼저 머지된 쪽 다음 줄에 추가* 등)
 - 정독 후 *의미 의도 추출* → 충돌 해결 → `git rebase --continue`
 
 #### 4-c. 판단 불가 → 사용자 호출
@@ -144,8 +144,8 @@ git -C "$WT_PATH" rebase dev
 
 | 케이스 | 위치 | 흐름 |
 |--------|------|------|
-| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` | 워크트리 안 task 문서 수정 → Step 6 Phase 커밋에 *코드 + 문서 = 한 커밋*에 포함 |
-| 등록 | `$MAIN_WT/.project/tasks/<vX.X>/...` | 워크트리 안 코드만 한 커밋 + 메인 워크트리 절대 경로 task 문서를 **proper-lockfile**로 별도 수정 (`bin/lib.js` `withMetaLock` — 머지 커밋 미포함, 메인 로컬 보존) |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` | 워크트리 안 task 문서 수정 → Step 6 Phase 커밋에 *코드 + 문서 = 한 커밋*에 포함 |
+| 등록 | `$MAIN_WT/.project/tasks/<NNN_slug>/...` | 워크트리 안 코드만 한 커밋 + 메인 워크트리 절대 경로 task 문서를 **proper-lockfile**로 별도 수정 (`bin/lib.js` `withMetaLock` — 머지 커밋 미포함, 메인 로컬 보존) |
 
 기록 형식 (task.md Result 섹션 안):
 ```markdown
@@ -233,7 +233,7 @@ closed-immutable.sh hook *허용* 영역 (status=closed 적용된 *후* 재수
 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).
+- 대상: `$WT_PATH/.project/tasks/<NNN_slug>/<NNN>_<slug>.md` (단일) 또는 `.../TASK-<NNN>_<slug>/task.md` (폴더 승격) + spec-diffs / screenshots / mockup (`<NNN_slug>` 공통, TASK_DOC_RULE §1.5).
 - **등록 케이스**: Step 6-5에서 메인 워크트리 직접 수정으로 처리 — 별도 커밋 X (워크트리 머지에 포함 X).
 
 #### 6-7. CHANGELOG 커밋 (해당 시)
@@ -245,6 +245,22 @@ docs: [TASK-<NNN>] 태스크 문서 완료
   - 등록 — `$MAIN_WT/.project/changelog/<YYYY-MM>.md` `withMetaLock` 갱신 (커밋 X)
 - 본 task에서 변경분 없으면 본 단계 *완전히 스킵* (빈 commit 금지).
 
+#### 6-8. 추적 마커 빈커밋 (폴백 — 머지 커밋 미생성 케이스 한정)
+
+> **조건**: 6-3 ~ 6-7을 모두 거쳤는데도 워크트리 브랜치가 dev보다 앞선 커밋이 **0개**인 경우에만 발동.
+> **발생 케이스**: `.project`가 gitignore된 프로젝트에서 *코드 변경 0 + 산출물이 메인 워크트리 직접 수정 task 문서뿐*인 docs/분석 전용 task. 워크트리에 추적 가능한 변경이 없어 6-3 ~ 6-7이 전부 스킵된 상태.
+> **이유**: 이대로 Step 8 `--no-ff` 머지를 하면 브랜치가 dev와 동일 커밋이라 *Already up to date* → 머지 커밋이 생성되지 않는다. 그러면 dev 히스토리에 `TASK-NNN` 흔적이 남지 않고, 이후 작업 브랜치가 자동 삭제(Step 13)되면 `getNextTaskNumber`가 진행중 브랜치·dev 머지 양쪽에서 번호를 찾지 못해 **다음 task가 같은 번호를 재사용/충돌**한다.
+
+```sh
+if [ "$(git -C "$WT_PATH" rev-list --count dev..HEAD)" -eq 0 ]; then
+  git -C "$WT_PATH" commit --allow-empty \
+    -m "docs: [TASK-<NNN>] 추적 마커 — 코드 0·.project gitignore (채번 보존)"
+fi
+```
+
+- 마커 커밋으로 브랜치가 dev보다 1커밋 앞서게 되어, Step 8 `--no-ff` 머지가 정상 머지 커밋을 생성한다 (머지 커밋 메시지의 브랜치명에 `TASK-NNN`이 포함되어 grep 추적 가능).
+- 추적 변경이 하나라도 있는 일반 task는 조건(`-eq 0`)에 걸리지 않아 발동하지 않는다 — 기존 동작 그대로.
+
 ### Step 7 — 메인 워크트리 uncommitted 검증 (머지 직전)
 
 ```sh
@@ -342,8 +358,9 @@ git -C "$MAIN_WT" worktree remove "$WT_PATH"
 - **자료 한계 보고** — 충돌 분석 시 *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` 사용 금지.
+- **빈 commit 금지 (예외 1건)** — CHANGELOG 변경 없으면 6-7 단계 스킵, `--allow-empty` 사용 금지. **단 Step 6-8 추적 마커 빈커밋만 예외** — 워크트리 브랜치가 dev보다 앞선 커밋이 0개일 때 채번 보존용으로 1개 허용.
 - **`-m` 옵션 머지 커밋에 사용 금지** — git 기본 메시지 사용.
+- **검수 서버/터널 정리는 자기 것만** — 본 task가 검수용으로 띄운 서버·터널(자기 포트 것)만 종료. `pkill -f` 류 광역 종료 금지 (다른 세션 프로세스까지 죽임). 상세: GIT_RULE "멀티세션 검수 환경".
 
 ## 상태 전이
 
@@ -359,4 +376,4 @@ git -C "$MAIN_WT" worktree remove "$WT_PATH"
 - **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`.
+- **BACKLOG.md 무관** — `.project/tasks/<NNN_slug>/BACKLOG.md` 체크 마킹은 `/task-init` Step 7.5가 처리(`[ ]` → `[x]` + `- TASK: TASK-NNN`). `[x]` = *task로 옮김* 의미라 close 시점에 추가 마킹 X. 완료 추적은 `npx @angar2/taskery status`(진행 중이면 dev 미머지가 정상) → 목록에 없을 때만 `git log dev --grep 'BL-NNN'` 순.

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

@@ -23,8 +23,8 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 | 케이스 | 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는 단일 소스) |
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<NNN_slug>/...` (`bin/lib.js` `withMetaLock`) | `$MAIN_WT/CLAUDE.md` |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/CLAUDE.md` (CLAUDE.md는 단일 소스) |
 
 self-check 명령은 워크트리(`$WT_PATH`)에서 실행 — 코드 변경이 워크트리 안에 있으므로 검증 대상도 거기.
 
@@ -49,7 +49,7 @@ self-check 명령은 워크트리(`$WT_PATH`)에서 실행 — 코드 변경이
 1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
 2. task 파일 Read:
    - 인자 있음 → 해당 파일.
-   - 인자 없음 → `ls .project/tasks/<vX.X>/` 결과 중 status=`planned` 또는 `developing`인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"진행할 task 없음. `/task-plan` 먼저 호출."* + 종료.
+   - 인자 없음 → `ls .project/tasks/<NNN_slug>/` 결과 중 status=`planned` 또는 `developing`인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"진행할 task 없음. `/task-plan` 먼저 호출."* + 종료.
 3. 상태 검증:
    - `planned` → 신규 진행 (Step 2 status 전환).
    - `developing` → 이어가기 (Step 2 skip — 이미 developing).
@@ -76,9 +76,9 @@ self-check 명령은 워크트리(`$WT_PATH`)에서 실행 — 코드 변경이
 
 ### Step 4 — Phase 0 처리 (있을 시)
 
-Dev Plan에 Phase 0(plan 문서 변경)이 있으면:
-1. `.project/plans/<vX.X>/<문서>.md` Edit.
-2. `.project/tasks/<vX.X>/spec-diffs/<NNN>_<slug>_spec-diff.md` 이미 `/task-plan`에서 만들어졌으면 그대로. 없으면 작성 (TASK_DOC_RULE §spec-diff 형식 참조).
+Dev Plan에 Phase 0(제품 관통 문서 변경)이 있으면:
+1. `.project/<문서>.md` (루트 제품 관통 문서) Edit. **DATA-MODEL/API-SPEC 상세는 구현 동반으로 여기서 확정** — plan-init이 미룬 스키마·엔드포인트 본문을 실제 구현 기준으로 채운다.
+2. `.project/tasks/<NNN_slug>/spec-diffs/<NNN>_<slug>_spec-diff.md` 이미 `/task-plan`에서 만들어졌으면 그대로. 없으면 작성 (TASK_DOC_RULE §spec-diff 형식 참조).
 3. Phase 0 `진행: [x]` Edit.
 
 ### Step 5 — flows/ 업데이트 (해당 시)
@@ -167,6 +167,14 @@ stash FRICTION_LOG #14+19 / #25 반영 — 유닛 테스트는 본 단계에서
 - 다음: /task-test TASK-<NNN> 으로 격리 세션 검증
 ```
 
+### Step 9 — 검수 서버 기동 (중단점·해당 시)
+
+**조건**: ① 이번 세션이 여기서 멈추고 사용자에게 제어를 넘김(= `/task-test`로 계속 진행하지 않음) + ② `CLAUDE.md`(코덱스 `AGENTS.md`)에 `## 검수 실행 명령`이 선언됨.
+
+- 두 조건 충족 시 — 그 명령으로 서버를 *백그라운드* 기동(포트 = 기준 포트 + TASK번호) + 접속 URL 보고. 모바일 검수가 필요하다고 판단되면 터널도 기동.
+- `/task-test`로 계속 진행하면 본 단계 생략 (마지막 단계에서만 기동 — 상세: GIT_RULE "멀티세션 검수 환경").
+- `## 검수 실행 명령` 미선언(CLI/라이브러리 등) 또는 사용자 *"안 띄워도 돼"* 발화 시 생략.
+
 ## 도구 가이드
 
 - **Read**: task 파일 / `CLAUDE.md` 검증 명령 / 관련 코드 정독
@@ -180,11 +188,12 @@ stash FRICTION_LOG #14+19 / #25 반영 — 유닛 테스트는 본 단계에서
 - **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`.
+- **디자인 산출 정독 의무 (stash FRICTION_LOG #14+19 / #12 일반화)** — task에 디자인 산출 (HTML 목업 / Figma / 디자인 파일 등) 있으면 메인이 *직접 Read* 후 구현. sub-agent 위임 금지 (요약만 받아 디자인 정합 깨짐). 구현 = 디자인 산출 기준 (역방향 X — 코드 편의로 디자인 어김 절대 X). 목업 위치 = `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html`.
 - **self-check FAIL 시 `developed` 전환 X** — 무리하게 상태 갱신 금지. 메인 자체 수정 시도 → 안 되면 사용자에게 보고. *"잘 될 거야"* 가정 금지.
 - **로그 심기 잊지 X** — Dev Plan 작성 시 `[로그]` 항목 명시되어 있으면 *반드시* 실제 로그 코드 삽입. 격리 세션 / 운영 디버깅 모두 의존.
 - **Result 섹션 진행만** — 테스트 결과는 `/task-test`가 기록. 메인이 *"잘 됐을 거야"* 가정 작성 금지.
 - **flows/ 업데이트 누락 X** — 신규 기능 / 로직 변경이면 `.project/flows/<module>.md` 갱신. 미갱신 시 다음 task가 옛 정보 보고 헤맴.
+- **워크트리에서 앱 실행·검수 시 의존성 심링크 금지** — 워크트리엔 의존성·빌드 산출물이 없는데, 메인 워크트리에서 심링크로 끌어오면 개발 서버 등이 로딩 실패(빈 화면)한다. 실행·검수하는 task면 워크트리 안에 실제로 의존성을 마련한다. 상세: GIT_RULE "워크트리 실행 환경" 섹션.
 
 ## 상태 전이
 

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

@@ -66,30 +66,30 @@ description: task 시작 — 워크트리 분기 + 6 섹션 빈 골격 + 헤더
 
 ### Step 2 — active plan 버전 확인
 
-1. `$MAIN_WT/.project/AGENT-GUIDE.md` Read → *활성 plan 버전* 추출 (예: `v1.0`).
-2. AGENT-GUIDE.md 없거나 활성 버전 누락 시 → 사용자에게 *"활성 plan 버전이 없는데 `/plan-init` 먼저 실행할까요?"* 묻고 중단.
-3. `$MAIN_WT/.project/plans/<vX.X>/` 디렉토리 존재 확인. 없으면 동일하게 `/plan-init` 안내 + 중단.
+1. `$MAIN_WT/.project/AGENT-GUIDE.md` Read → *활성 plan* 추출 (예: `001_mvp` — `NNN_slug` 폴더명).
+2. AGENT-GUIDE.md 없거나 활성 plan 누락 시 → 사용자에게 *"활성 plan 버전이 없는데 `/plan-init` 먼저 실행할까요?"* 묻고 중단.
+3. `$MAIN_WT/.project/plans/<NNN_slug>/` 디렉토리 존재 확인. 없으면 동일하게 `/plan-init` 안내 + 중단.
 
 ### Step 3 — 분기 판단 + 메타 수집
 
 직전 대화 정독:
 - 작업 주제 / 유형 / 출처 / 규모 추정 가능?
   - **추정 가능** → 분기 1 (제안):
-    *"직전 맥락 보니 다음 task 만들까요? 주제: <X> / 유형: <Y> / 출처: <Z> / 규모: <W> / 플랜: <vX.X>. 어떠세요?"*
+    *"직전 맥락 보니 다음 task 만들까요? 주제: <X> / 유형: <Y> / 출처: <Z> / 규모: <W> / plan: <NNN_slug>. 어떠세요?"*
     사용자 답 — *"OK"* / *"규모는 large야"* / *"유형은 bug야"* 등 부분 수정 받음.
   - **추정 불가** → 분기 2 (인터뷰): 한 번에 한 질문씩.
     - Q1: *"무슨 작업인가요? (한 줄로)"*
     - Q2: *"유형? (feature / bug / improvement / refactor / docs / chore)"*
     - Q3: *"출처? (백로그 BL-NNN / 로드맵 RM-NNN / 직접 요구사항 DR)"*
     - Q4: *"규모? (micro / small / medium / large) — 잘 모르겠으면 추정 알려드림."*
-    - (필요 시) Q5: *"플랜 버전 `<vX.X>` 맞나요?"*
+    - (필요 시) Q5: *"plan `<NNN_slug>` 맞나요?"*
 
 수집 항목 (모두 확정되어야 진행):
 - 주제 (한국어 — kebab-slug 변환은 Step 4)
 - 유형: `feature` / `bug` / `improvement` / `refactor` / `docs` / `chore`
 - 출처: `BL-NNN` / `RM-NNN` / `DR`
 - 규모: `micro` / `small` / `medium` / `large`
-- 플랜 버전: 활성 버전 그대로 (Step 2에서 가져온 값)
+- plan: 활성 plan 그대로 (Step 2에서 가져온 `NNN_slug` 값)
 
 ### Step 4 — TASK 번호 결정 + 결정적 슬러그 + SSoT 안전망
 
@@ -116,8 +116,8 @@ NEXT=$((MAX + 1))
 
 #### 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 → 항목 메타 파싱
+- BL: `$MAIN_WT/.project/tasks/<활성 plan>/BACKLOG.md` Read → `BL-NNN` 블록 파싱 → `{ status, type, title, slug, summary, target, taskNums }` (활성 plan은 `AGENT-GUIDE.md`에서 검출. `bin/lib.js`의 `parseBacklogItem(mainWtPath, blId)` 호출 권장). 개요 / 대상 영역 → task.md §1 Requirements 초안에 자동 복사 (얕은 분석이 task 문서 시작점)
+- RM: `$MAIN_WT/.project/plans/<활성 plan>/ROADMAP.md` Read → `RM-NNN` grep → 항목 메타 파싱
 - DR: 사용자 발화에서 주제 그대로
 
 #### 4.2.5 이미 `[x]` BL 재진행 케이스
@@ -149,8 +149,8 @@ git -C "$MAIN_WT" branch --no-merged dev --list \
 
 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)
+   - **폴더 승격 조건**: *사용자 명시* 시에만 (*"폴더로 만들어줘"* 류). 규모 large·추가 자료 다수여도 자동 승격하지 않는다 — 기본은 항상 단일 파일. 기능 자체는 유지(사용자가 원하면 그대로 사용).
+   - **spec-diffs / screenshots / mockup은 `<NNN_slug>` 공통** — 단일/폴더 모두 `.project/tasks/<NNN_slug>/{spec-diffs,screenshots,mockup}/`에 위치. (TASK_DOC_RULE §1.5)
 2. 브랜치명 산출 (멀티세션 형식):
    ```
    {타입}/{개발자}_TASK-NNN_{출처}_{슬러그}
@@ -184,8 +184,8 @@ git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
 
 | 결과 | 케이스 | 작성 위치 |
 |------|--------|----------|
-| exit 0 | **등록됨** (퍼블릭 리포 default) | **메인 워크트리** (`$MAIN_WT/.project/tasks/<vX.X>/`) — proper-lockfile로 안전 쓰기. 멀티세션 공유 단일 소스. dev untracked (git 자동 무시) |
-| exit 1 | **미등록** | **워크트리 안** (`$WT_PATH/.project/tasks/<vX.X>/`) — 워크트리 커밋 + 머지 시 dev에 반영 |
+| exit 0 | **등록됨** (퍼블릭 리포 default) | **메인 워크트리** (`$MAIN_WT/.project/tasks/<NNN_slug>/`) — proper-lockfile로 안전 쓰기. 멀티세션 공유 단일 소스. dev untracked (git 자동 무시) |
+| exit 1 | **미등록** | **워크트리 안** (`$WT_PATH/.project/tasks/<NNN_slug>/`) — 워크트리 커밋 + 머지 시 dev에 반영 |
 
 빈 골격 형식 (TASK_DOC_RULE §1.3 참조):
 
@@ -194,7 +194,7 @@ git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
 
 | 생성일 | 플랜 | 유형 | 규모 | 상태 |
 |--------|------|------|------|------|
-| <YYYY-MM-DD> | <vX.X> | <유형> | <규모> | draft |
+| <YYYY-MM-DD> | <NNN_slug> | <유형> | <규모> | draft |
 
 ## Requirements
 
@@ -242,7 +242,7 @@ git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
 - 워크트리: <WT_PATH>
 - 브랜치: <BRANCH>
 - task 문서: <TASK_DOC_PATH> (메인 워크트리 / 워크트리 안 — 위 케이스에 따라)
-- 헤더: <생성일> / <vX.X> / <유형> / <규모> / draft
+- 헤더: <생성일> / <NNN_slug> / <유형> / <규모> / draft
 - BL 마킹: BL-<NNN> [x] (BL 출처 시. RM/DR이면 생략)
 - 다음: /task-plan TASK-<NNN> 으로 기획 채우기 (워크트리 폴더에서 새 세션 열어 진행 / 메인 세션 그대로 진행 / 메인이 서브 세션 spawn 등 운영 모델 자유)
 ```
@@ -250,7 +250,7 @@ git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
 ## 도구 가이드
 
 - **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`
+- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` / `$MAIN_WT/.project/tasks/<활성 plan>/BACKLOG.md` / `$MAIN_WT/.project/plans/<활성 plan>/ROADMAP.md`
 - **Write**: task.md 빈 골격 작성 (위치는 .gitignore 케이스에 따라)
 - **AskUserQuestion**: 분기 2 인터뷰 (한 번에 한 질문)
 
@@ -258,8 +258,8 @@ git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
 
 - **워크트리 생성 + 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
+  - **허용 (화이트리스트)**: `$MAIN_WT/.project/plans/<활성 plan>/ROADMAP.md` §4(다음 작업 영역) 확인 / SSoT 조회 / TASK-NNN 계산 / 빈 골격 Write
+  - **금지 (블랙리스트)**: ARCHITECTURE.md / API-SPEC.md / FEATURES.md 등 `.project/` 루트 제품 관통 문서 본문 Read / 도메인 코드 Read · Grep / 기존 task 본문 Read
   - 본문 정보 수집은 *다음 단계 `/task-plan`*에서 수행.
 - **자동 추정 진행 X** — 직전 맥락 명확해도 *제안 + 사용자 OK* 거친 후 워크트리/파일 생성.
 - **상태는 `draft` 고정** — `/task-init` 끝의 상태는 `draft` 외 작성 금지.

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

@@ -21,10 +21,10 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 `.gitignore` 케이스 분기:
 
-| 케이스 | task 문서 위치 | 9 기획 문서 위치 | 동시 쓰기 |
+| 케이스 | task 문서 위치 | 제품 관통 문서 위치 | 동시 쓰기 |
 |--------|--------------|----------------|----------|
-| 등록 (퍼블릭 리포 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 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<NNN_slug>/...` | `$MAIN_WT/.project/<doc>.md` (루트 평평) | `withMetaLock` (`bin/lib.js`) |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/.project/<doc>.md` (제품 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
 
 본문 모든 `.project/...` 경로는 *위 분기에 따라* 적용. spec-diff / mockup / screenshots는 task 문서와 같은 위치.
 
@@ -38,8 +38,8 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 인자 = (선택) `TASK-NNN` 또는 자동 선택.
 
 분기:
-- **인자 명시**: `.project/tasks/<vX.X>/<NNN>_*.md` 또는 `TASK-<NNN>_*/task.md` 찾아서 진행.
-- **인자 없음**: 활성 plan 버전의 `.project/tasks/<vX.X>/` 안 *상태=draft인 가장 최근 task* 자동 선택 + confirm.
+- **인자 명시**: `.project/tasks/<NNN_slug>/<NNN>_*.md` 또는 `TASK-<NNN>_*/task.md` 찾아서 진행.
+- **인자 없음**: 활성 plan의 `.project/tasks/<NNN_slug>/` 안 *상태=draft인 가장 최근 task* 자동 선택 + confirm.
 
 ## 단계
 
@@ -48,7 +48,7 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
 2. task 파일 Read:
    - 인자 있음 → 해당 파일.
-   - 인자 없음 → `ls .project/tasks/<vX.X>/` 결과 중 status=draft인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"draft 상태 task가 없네요. `/task-init` 먼저 호출하세요."* + 종료.
+   - 인자 없음 → `ls .project/tasks/<NNN_slug>/` 결과 중 status=draft인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"draft 상태 task가 없네요. `/task-init` 먼저 호출하세요."* + 종료.
 3. 상태 = `draft` 검증. 다른 상태면 종료 + 안내.
 
 ### Step 2 — Requirements 인터뷰 + 증폭
@@ -112,8 +112,9 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
    - **어떻게**: 구현 방법 1~3줄
    - **완료 기준**: 끝났다고 판단할 기준 (예: *"API endpoint 200 반환"*)
    - **진행**: `[ ]`
-4. **Phase 0 (선택) — plan 문서 변경 검토**:
-   - 본 task가 `.project/plans/<vX.X>/` 9 기획 문서 중 어느 것을 *수정/추가/삭제*해야 하는지 검토.
+4. **Phase 0 (선택) — 제품 관통 문서 변경 검토**:
+   - 본 task가 `.project/` 루트 제품 관통 문서(FEATURES / UX-UI / DATA-MODEL / API-SPEC / SERVICE-POLICY / TECH-STACK / ARCHITECTURE) 중 어느 것을 *수정/추가/삭제*해야 하는지 검토.
+   - **DATA-MODEL / API-SPEC 상세는 여기가 채우는 주체** — plan-init은 의도/빈 헤더까지만 두고 미뤘다. 본 task가 스키마·엔드포인트를 *구현 동반*으로 확정해 본문을 채운다(선기획 금지의 귀결).
    - 변경 있음 → Phase 0에 명시 + `spec-diffs/<NNN>_<slug>_spec-diff.md` 파일 생성 (Step 6).
    - 변경 없음 → Phase 0 생략.
 5. **Phase 점진 작성 OK** — 처음부터 모든 Phase 일괄 작성 금지. 지금 명확한 Phase만 작성하고 진행 중 추가 가능.
@@ -121,8 +122,8 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 ```markdown
 ## Dev Plan
 
-### Phase 0 — plans/<vX.X>/ 기획 문서 변경 (선택)
-- 변경 문서: <FEATURES.md / API-SPEC.md / ...>
+### Phase 0 — 제품 관통 문서(.project/ 루트) 변경 (선택)
+- 변경 문서: <FEATURES.md / API-SPEC.md / DATA-MODEL.md / ...>
 - 변경 내용: <요약>
 - spec-diff: `spec-diffs/<NNN>_<slug>_spec-diff.md`
 - 진행: [ ]
@@ -167,12 +168,12 @@ Step 2 Requirements 인터뷰 결과로 본 task가 *UX/UI 구현 (페이지/컴
 1. 메인이 HTML 목업 생성 — 정적 HTML/CSS (외부 라이브러리 X, 단일 파일 안 inline style + 필요 시 vanilla JS):
    - 시각 영역 (레이아웃 / 색상 / 간격 / 타이포 / 호버 효과)
    - 인터랙션 (가능한 범위 — 클릭 / 호버 시뮬)
-2. 사용자에게 *"브라우저로 `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
+2. 사용자에게 *"브라우저로 `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
 3. 사용자 ✓ → 승인 완료, 4 진행. ✗ → 메인이 수정 후 재승인 요청.
 
 #### 4. 파일 위치 / 네이밍
 
-- 위치: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+- 위치: `.project/tasks/<NNN_slug>/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">` 등).
 
@@ -225,7 +226,7 @@ Test Plan = *본 task에서 구현한 요구사항이 정상 동작하는지*
 | 1 | <한 줄 설명> | [AUTO] / [USER] | <카탈로그 방식> | <명확한 기대값> |
 | 2 | ... | ... | ... | ... |
 
-(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html`
 ```
 
 #### 시각 영역 fix 사이클 사전 예고 (stash FRICTION_LOG #14 반영)
@@ -271,13 +272,13 @@ Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋
 
 ### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
 
-1. `.project/tasks/<vX.X>/spec-diffs/` 디렉토리 존재 확인 (없으면 `mkdir -p`).
+1. `.project/tasks/<NNN_slug>/spec-diffs/` 디렉토리 존재 확인 (없으면 `mkdir -p`).
 2. `spec-diffs/<NNN>_<slug>_spec-diff.md` Write — 형식:
 
 ```markdown
 # Spec Diff — TASK-<NNN> <제목>
 
-## <plans/<vX.X>/<문서명>.md> [NEW|MOD|DEL]
+## <.project/<문서명>.md> [NEW|MOD|DEL]
 
 +++
 + <추가/변경 내용>
@@ -308,7 +309,7 @@ Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋
 
 ## 도구 가이드
 
-- **Read**: task 파일 / 활성 plan 9 기획 문서 / 관련 코드 정독
+- **Read**: task 파일 / `.project/` 루트 제품 관통 문서 / 관련 코드 정독
 - **Grep / Glob**: Scope 코드 서치 (관련 함수/파일 탐색)
 - **Edit**: task 파일 4 섹션 채우기 + status 전환
 - **Write**: spec-diff 파일 (Phase 0 변경 시)

package/template/shared/skills/task-test/SKILL.md

@@ -23,8 +23,8 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 | 케이스 | task 문서 위치 | 격리 세션 작업 디렉토리 |
 |--------|--------------|---------------------|
-| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` | `$WT_PATH` (워크트리 — 코드 변경 위치) |
-| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안) | `$WT_PATH` (워크트리) |
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<NNN_slug>/...` | `$WT_PATH` (워크트리 — 코드 변경 위치) |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안) | `$WT_PATH` (워크트리) |
 
 격리 세션은 *워크트리 안*에서 검증/테스트 명령 실행 (`$MAIN_WT/CLAUDE.md`의 `## 검증 명령` / `## 테스트 명령` 단일 진실 소스).
 
@@ -122,7 +122,7 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 ```
 
 **구현 디테일**:
-- `<ABSOLUTE_PATH_TO_TASK_MD>` 자리에 `.project/tasks/<vX.X>/<NNN>_<slug>.md` (또는 폴더 승격 시 `<...>/task.md`)의 절대 경로 삽입.
+- `<ABSOLUTE_PATH_TO_TASK_MD>` 자리에 `.project/tasks/<NNN_slug>/<NNN>_<slug>.md` (또는 폴더 승격 시 `<...>/task.md`)의 절대 경로 삽입.
 - Task tool의 `subagent_type`: `general-purpose` (도구 풀 다 필요).
 - Task tool의 `description`: `Isolated test for TASK-<NNN>`.
 
@@ -183,6 +183,8 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 
 격리 세션이 `[USER]` 시나리오 또는 자동화 불가능한 시나리오(UI 인터랙션 / 시각 디자인 / 사용자 입력 등) 발견 시. **자동 PASS 전이 X — 사용자 직접 검수 PASS 받은 후에만 `tested` 전이**.
 
+> **검수 서버 먼저 기동** (`## 검수 실행 명령` 선언 + 시각/UI 검수 항목 포함 시): 체크리스트를 제시하기 *전에* 서버를 백그라운드 기동(포트 = 기준 포트 + TASK번호)하고 접속 URL을 함께 제공한다 — 사용자가 실제 화면을 보며 ✓/✗ 검수하도록. 격리 세션이 기능상 이미 띄웠으면 재사용. 사용자 *"안 띄워도 돼"* 시 생략. 상세: GIT_RULE "멀티세션 검수 환경".
+
 1. 메인이 사용자에게 *체크리스트 형식*으로 항목 보고 (stash FRICTION_LOG #14+19 반영):
 
 ```
@@ -202,6 +204,15 @@ USER 검수 — N 항목 (목업 기준: <mockup path — 있을 시>)
 
 ### Step 6 — 결과 보고 (위 분기별 메시지)
 
+### Step 7 — 검수 서버 기동 (PASS 후 세션 종료·해당 시)
+
+**조건**: ① 종합 판정 PASS + 이번 세션이 여기서 멈추고 사용자에게 제어를 넘김(= `/task-close`로 바로 진행하지 않음) + ② `CLAUDE.md`(코덱스 `AGENTS.md`)에 `## 검수 실행 명령`이 선언됨.
+
+- 두 조건 충족 시 — 그 명령으로 서버를 *백그라운드* 기동(포트 = 기준 포트 + TASK번호) + 접속 URL 보고. 모바일 검수가 필요하다고 판단되면 터널도 기동.
+- 격리 세션 검증이 *기능상* 이미 서버를 띄워 둔 경우 — 죽였다 다시 띄우지 말고 그대로 두고 URL만 보고.
+- **FAIL → 수정 흐름에서는 기동하지 않는다** (수정하러 가는 단계라 검수 무의미). **UNCERTAIN 검수는 Step 5에서 이미 기동**했으므로 여기서 중복 기동 X.
+- `## 검수 실행 명령` 미선언 또는 사용자 *"안 띄워도 돼"* 발화 시 생략. 상세: GIT_RULE "멀티세션 검수 환경".
+
 ## 도구 가이드
 
 - **Read**: task 파일 / `## Test Plan` + `## Dev Plan` 정독