@angar2/taskery 0.1.0 → 0.1.2

package/bin/status.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * bin/status.js
+ * `npx @angar2/taskery status` — 멀티세션 현황 요약.
+ *
+ * 출력:
+ *   - 메인 워크트리 + 현재 브랜치
+ *   - projectId / stale_days / lock_timeout_ms
+ *   - 진행중 태스크 (SSoT) + 각 워크트리 폴더 존재 여부 + 마지막 커밋 시각
+ *   - stale 의심 항목 (케이스 A/B/C/D)
+ *   - 머지 락 상태 (잡혀 있으면 누가 잡고 있는지)
+ *
+ * 본 명령은 *변경 X — 읽기 전용*. 정리는 `taskery prune`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  gitCapture,
+  getMainWorktreePath,
+  getActiveTasks,
+  getWorktreesRoot,
+  getMergeLockPath,
+  DEFAULT_STALE_DAYS,
+  DEFAULT_LOCK_TIMEOUT_MS,
+} = require('./lib');
+
+function daysAgo(date) {
+  const now = Date.now();
+  const ms = now - date.getTime();
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+function main() {
+  // 1. 메인 워크트리 + manifest
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery status 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  const manifest = readManifest(path.join(mainWt, MANIFEST_NAME));
+  if (!manifest) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+
+  const projectId = manifest.projectId;
+  const staleDays = manifest.stale_days ?? DEFAULT_STALE_DAYS;
+  const lockTimeoutMs = manifest.lock_timeout_ms ?? DEFAULT_LOCK_TIMEOUT_MS;
+
+  const currentBranch = gitCapture(mainWt, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const isOnDev = currentBranch === 'dev';
+
+  console.log(`\ntaskery status\n`);
+  console.log(`메인 워크트리: ${mainWt}`);
+  console.log(`현재 브랜치: ${currentBranch}${isOnDev ? '' : ' ⚠ (메인 워크트리 = dev 정책 위배)'}`);
+  console.log(`projectId: ${projectId}`);
+  console.log(`stale_days: ${staleDays} / lock_timeout_ms: ${lockTimeoutMs}\n`);
+
+  // 2. 머지 락 상태
+  const lockPath = getMergeLockPath(projectId);
+  const lockDir = lockPath + '.lock'; // proper-lockfile은 <file>.lock 디렉토리 생성
+  if (fs.existsSync(lockDir)) {
+    let lockInfo = '';
+    try {
+      const stat = fs.statSync(lockDir);
+      const ageMs = Date.now() - stat.mtimeMs;
+      lockInfo = ` (잡힘 ${Math.round(ageMs / 1000)}초 전)`;
+    } catch (_) {}
+    console.log(`머지 락: 활성${lockInfo}`);
+  } else {
+    console.log(`머지 락: 비활성`);
+  }
+  console.log();
+
+  // 3. 진행중 태스크 (SSoT)
+  const active = getActiveTasks(mainWt);
+  console.log(`진행중 태스크 (SSoT, ${active.length}건):`);
+
+  if (active.length === 0) {
+    console.log(`  (없음)`);
+  } else {
+    const worktreesRoot = getWorktreesRoot(projectId);
+    for (const t of active) {
+      const wtPath = path.join(worktreesRoot, `TASK-${String(t.taskNum).padStart(3, '0')}_${t.src}_${t.slug}`);
+      const wtExists = fs.existsSync(wtPath);
+      const lastCommit = gitCapture(mainWt, [
+        'log', '-1', '--format=%ci', t.branch,
+      ], { allowFail: true });
+      const lastDate = lastCommit ? new Date(lastCommit) : null;
+      const daysOld = lastDate ? daysAgo(lastDate) : null;
+
+      console.log(`  ${t.branch}`);
+      console.log(`    워크트리: ${wtPath}${wtExists ? '' : ' ⚠ 폴더 없음 (케이스 A — prune 필요)'}`);
+      if (lastDate) {
+        console.log(`    마지막 커밋: ${lastCommit} (${daysOld}일 전)${daysOld >= staleDays ? ' ⚠ stale 의심 (케이스 B/C)' : ''}`);
+      } else {
+        console.log(`    마지막 커밋: (조회 실패)`);
+      }
+      if (wtExists) {
+        const rebaseApply = path.join(wtPath, '.git', 'rebase-apply');
+        const rebaseMerge = path.join(wtPath, '.git', 'rebase-merge');
+        if (fs.existsSync(rebaseApply) || fs.existsSync(rebaseMerge)) {
+          console.log(`    ⚠ rebase 잔여 상태 (케이스 D) — taskery prune 또는 워크트리에서 git rebase --abort`);
+        }
+      }
+    }
+  }
+  console.log();
+
+  // 4. 워크트리 폴더 vs SSoT mismatch (orphan)
+  const worktreesRoot = getWorktreesRoot(projectId);
+  if (fs.existsSync(worktreesRoot)) {
+    const folders = fs.readdirSync(worktreesRoot).filter((n) => n.startsWith('TASK-'));
+    const activeFolders = new Set(
+      active.map(
+        (t) => `TASK-${String(t.taskNum).padStart(3, '0')}_${t.src}_${t.slug}`,
+      ),
+    );
+    const orphans = folders.filter((f) => !activeFolders.has(f));
+    if (orphans.length > 0) {
+      console.log(`⚠ SSoT에 없는 워크트리 폴더 ${orphans.length}건 (이미 dev 머지된 잔존?):`);
+      for (const o of orphans) {
+        console.log(`  ${path.join(worktreesRoot, o)}`);
+      }
+      console.log(`  → 'taskery prune' 으로 정리`);
+      console.log();
+    }
+  }
+
+  console.log(`기타 명령:`);
+  console.log(`  npx @angar2/taskery prune   stale 워크트리 / 브랜치 대화형 정리`);
+  console.log();
+}
+
+try {
+  main();
+} catch (e) {
+  console.error(`taskery status 실패: ${e.message}`);
+  process.exit(1);
+}

package/bin/taskery.js

@@ -6,6 +6,8 @@
  * 서브커맨드:
  *   init    — 현재 디렉토리에 taskery 자산 카피 + manifest 생성
  *   update  — 최신 버전 fetch + manifest 비교 + 머지 갱신
+ *   status  — 멀티세션 현황 요약 (진행중 태스크 / 워크트리 / 머지 락, 0.1.2+)
+ *   prune   — stale 워크트리 / 브랜치 대화형 정리 (0.1.2+)
  *   help    — 사용법 출력
  */
 
@@ -28,6 +30,8 @@ function help() {
 사용법:
   npx @angar2/taskery init      현재 디렉토리에 taskery 자산 설치
   npx @angar2/taskery update    최신 버전 fetch + 머지 갱신
+  npx @angar2/taskery status    멀티세션 현황 (진행중 태스크 / 워크트리 / 머지 락)
+  npx @angar2/taskery prune     stale 워크트리 / 브랜치 대화형 정리
   npx @angar2/taskery help      도움말
 
 새 프로젝트 시작:
@@ -44,6 +48,27 @@ switch (sub) {
   case 'update':
     runScript('update.js');
     break;
+  case 'status':
+    runScript('status.js');
+    break;
+  case 'prune':
+    if (process.argv[3] === '--help' || process.argv[3] === '-h') {
+      console.log(`taskery prune — stale 워크트리 / 브랜치 대화형 정리
+
+사용법:
+  npx @angar2/taskery prune
+
+설명:
+  .taskery-manifest.json의 stale_days (기본 30일) 기준으로 비활성 워크트리 + 브랜치를 대화형 정리합니다.
+  케이스 분기: A (워크트리 + 브랜치 모두 stale) / B (브랜치만 stale) / C (워크트리 폴더 잔존) / D (정합 영역).
+  각 케이스마다 y/n/k 선택 가능 (y = 삭제 / n = 건너뜀 / k = 보존 명시).
+
+상세: https://github.com/angar2/taskery
+`);
+      break;
+    }
+    runScript('prune.js');
+    break;
   case 'help':
   case '--help':
   case '-h':

package/bin/update.js

@@ -3,7 +3,7 @@
  * bin/update.js
  * `npx @angar2/taskery update` — template/ 최신 자산과 사용자 측 비교 + 머지 갱신.
  *
- * 머지 로직 (§9-1):
+ * 머지 로직 (DISTRIBUTION.md §6):
  *   1. .taskery-manifest.json (cwd) 읽기 — 없으면 에러 ('init' 먼저)
  *   2. template/ 정독 → 새 해시 맵
  *   3. 각 파일 분기:
@@ -31,6 +31,9 @@ const {
   readManifest,
   getPackageVersion,
   isLocalOverride,
+  generateProjectId,
+  DEFAULT_STALE_DAYS,
+  DEFAULT_LOCK_TIMEOUT_MS,
 } = require('./lib');
 
 async function confirm(msg) {
@@ -146,15 +149,36 @@ async function main() {
     }
   }
 
-  // 5. manifest 갱신
+  // 5. manifest 갱신 — 멀티세션(0.1.2+) 필드 누락 시 자동 마이그레이션
+  const migration = { projectId: false, stale_days: false, lock_timeout_ms: false };
+  const projectId = oldManifest.projectId || (migration.projectId = true, generateProjectId());
+  const stale_days =
+    typeof oldManifest.stale_days === 'number'
+      ? oldManifest.stale_days
+      : (migration.stale_days = true, DEFAULT_STALE_DAYS);
+  const lock_timeout_ms =
+    typeof oldManifest.lock_timeout_ms === 'number'
+      ? oldManifest.lock_timeout_ms
+      : (migration.lock_timeout_ms = true, DEFAULT_LOCK_TIMEOUT_MS);
+
   const newManifest = {
     version: getPackageVersion(),
     installed_at: oldManifest.installed_at,
     updated_at: new Date().toISOString(),
+    projectId,
+    stale_days,
+    lock_timeout_ms,
     files: newFiles,
   };
   writeManifest(newManifest, manifestPath);
 
+  const migratedFields = Object.entries(migration)
+    .filter(([, added]) => added)
+    .map(([k]) => k);
+  if (migratedFields.length > 0) {
+    console.log(`  manifest 마이그레이션: ${migratedFields.join(', ')} 필드 추가`);
+  }
+
   // 결과 보고
   console.log(`\n✅ taskery update 완료`);
   console.log(`   동일: ${summary.unchanged}, 신규: ${summary.new}, 자동 갱신: ${summary.autoUpdated}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angar2/taskery",
-  "version": "0.1.0",
-  "description": "Lightweight task system for Claude Code — 1 메인 세션 + 스킬 8종 + catastrophic hook 안전망 3종",
+  "version": "0.1.2",
+  "description": "Lightweight task system for Claude Code — 1 메인 세션(또는 멀티세션) + 스킬 9종 + catastrophic hook 안전망 2종",
   "bin": {
     "taskery": "bin/taskery.js",
     "create-taskery": "bin/create.js"
@@ -38,6 +38,10 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "git": ">=2.31.0"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
   }
 }

package/template/.claude/hooks/closed-immutable.sh

@@ -10,7 +10,8 @@
 # 차단 안 함 (의도적):
 #   - .project/tasks/<vX.X>/spec-diffs/*.md — 역사적 자료, 자유 수정
 #   - .project/tasks/<vX.X>/screenshots/* — 자유
-#   - 폴더 승격 task 폴더 안 추가 자료 — 자유
+#   - .project/tasks/<vX.X>/mockup/*.html — UX/UI 목업, 자유 수정 (vX.X 공통)
+#   - 폴더 승격 task 폴더 안 추가 자료 (서브 문서 등) — 자유
 #   - 코드 영역 — closed task 코드 재수정은 *새 task로 처리*가 정상 흐름
 #
 # 우회 (의도적으로 closed task를 풀어 다시 진행해야 하는 경우):
@@ -32,9 +33,9 @@ except Exception:
 " 2>/dev/null)
 
 # task.md 본 파일 매칭 (단일 + 폴더 승격)
-# - 단일: .project/tasks/v*/<NNN>_<slug>.md (NNN_<slug> 패턴 — vX.X 직속, spec-diffs/screenshots 하위 X)
+# - 단일: .project/tasks/v*/<NNN>_<slug>.md (NNN_<slug> 패턴 — vX.X 직속, spec-diffs/screenshots/mockup 하위 X)
 # - 폴더: .project/tasks/v*/TASK-<NNN>_<slug>/task.md
-# spec-diffs/ + screenshots/ 직속 파일은 매칭 안 됨 (보호 대상 X)
+# spec-diffs/ + screenshots/ + mockup/ 직속 파일은 매칭 안 됨 (보호 대상 X)
 if ! echo "$FILE_PATH" | grep -qE '\.project/tasks/v[^/]+/([0-9]+_[^/]+\.md|TASK-[^/]+/task\.md)$'; then
   exit 0
 fi
@@ -67,7 +68,7 @@ print(m.group(1) if m else '')
 if [ "$STATUS" = "closed" ]; then
   echo "closed-immutable: '$FILE_PATH' 차단. task '$TASK_MD' 상태가 'closed' — 재수정 금지." >&2
   echo "  의도적 재진입 필요 시: sed로 헤더 status를 'developing' 또는 다른 상태로 직접 변경 후 Edit 가능." >&2
-  echo "  *closed task 코드 / spec-diffs / screenshots*는 보호 영역 외 — 자유 수정. 단 코드 변경은 *새 task로 처리*가 정상 흐름." >&2
+  echo "  *closed task 코드 / spec-diffs / screenshots / mockup*은 보호 영역 외 — 자유 수정. 단 코드 변경은 *새 task로 처리*가 정상 흐름." >&2
   exit 2
 fi
 

package/template/.claude/hooks/git-guard.sh

@@ -43,7 +43,7 @@ fi
 
 # 2. git commit --no-verify 차단
 if echo "$CMD" | grep -qE 'git\s+commit\b.*--no-verify'; then
-  echo "git-guard: 'git commit --no-verify' 차단. pre-commit-verify hook 우회 금지. (.project/rules/GIT_RULE.md §금지 사항)" >&2
+  echo "git-guard: 'git commit --no-verify' 차단. commit hook 우회 금지. (.project/rules/GIT_RULE.md §금지 사항)" >&2
   exit 2
 fi
 

package/template/.claude/settings.json

@@ -4,8 +4,7 @@
       {
         "matcher": "Bash",
         "hooks": [
-          { "type": "command", "command": ".claude/hooks/git-guard.sh" },
-          { "type": "command", "command": ".claude/hooks/pre-commit-verify.sh" }
+          { "type": "command", "command": ".claude/hooks/git-guard.sh" }
         ]
       },
       {

package/template/.claude/skills/add-backlog/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: add-backlog
+description: 사용자 발화로 *버전별* tasks/<vX.X>/BACKLOG.md에 task 후보 1건 추가 — 얕은 분석(개요/대상 영역) + BL-NNN 채번 + withMetaLock 직렬화 (0.1.2+)
+---
+
+# /add-backlog
+
+## 개요
+
+`/add-backlog`는 사용자 발화를 받아 *버전별 백로그* `.project/tasks/<vX.X>/BACKLOG.md`에 task 후보를 1건씩 누적한다. 멀티세션 환경에서 `withMetaLock`으로 동시 쓰기 직렬화. **얕은 분석**만 — 코드 직접 탐색 X, 추정 수준. 본격 분석은 다음 단계 `/task-plan`에서.
+
+글로벌 `.project/BACKLOG.md` (plan 기획 후보 카탈로그) 는 `/plan-init` 영역으로 본 스킬 무관.
+
+## 호출 시점
+
+- 사용자 명시 호출: `/add-backlog 로그인 빈 화면 떠`
+- 발화 캐치: *"~ 백로그에 추가해 줘"* / *"백로그에 ~"* 등 백로그 추가 의도 발화 description 매칭으로 메인이 자동 발동
+
+## 입력 처리
+
+- 무인자 호출: 사용자가 *"백로그 추가"*만 말한 경우 — 어떤 항목인지 한 줄 인터뷰
+- 인자 호출: 인자에 백로그 후보 주제. 1건 기본. 다건 명시 시 순차 처리
+
+## 단계 (Step 1~6)
+
+### Step 1 — 사전 검증
+
+- 메인 워크트리 검출:
+  ```sh
+  MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+  ```
+- 메인 워크트리 dev 체크아웃 검증 — 위배 시 사용자 호출 + 중단
+- 활성 버전 검출 — `$MAIN_WT/.project/AGENT-GUIDE.md` `## 활성 plan 버전` 섹션 다음 비어 있지 않은 첫 줄에서 `vX.X` 패턴 추출
+- BACKLOG.md 경로 = `$MAIN_WT/.project/tasks/<vX.X>/BACKLOG.md`. 부재 시 사용자 호출: *"`/plan-init` 먼저 호출해 활성 버전 디렉토리 + 빈 BACKLOG.md 생성 필요"* + 중단
+
+### Step 2 — 백로그 항목 후보 추출
+
+- 사용자 발화에서 1건 추출. 다건 명시 시 순차 처리 (각 1건씩 본 흐름 반복)
+- 입력이 비어 있으면 사용자에게 *"어떤 항목? 한 줄로 알려줘"* 인터뷰
+
+### Step 3 — 얕은 분석 (LLM, 코드 탐색 X)
+
+추정 수준의 메타 산출:
+- **유형** (`feature` / `bug` / `improve` / `refactor` / `docs` / `chore`) — 자동 추정, 모호 시 사용자 confirm
+- **제목** — 한 줄, 간결, 한국어
+- **개요** — 한 줄. bug → 원인 추정 / feature → 구상 / improve → 개선 방향
+- **대상 영역** — 한 줄. 이 파일 / 모듈일 거다 — 추정 수준
+
+> *코드 직접 탐색 금지*. 본격 분석은 다음 단계 `/task-plan`에서. 본 스킬은 *메모지 누적*만.
+
+### Step 4 — 결정적 슬러그 산출
+
+- 한국어 제목 → 영어 *의미 변환* → kebab-case (3 단어 이내, 음역 X)
+- 예: *"로그인 페이지 빈 화면"* → `login-empty-page` / *"다크모드 토글"* → `dark-mode-toggle`
+
+### Step 5 — BL-NNN 채번 + append (withMetaLock 직렬화)
+
+`bin/lib.js`의 `appendBacklogItem(mainWtPath, meta)` 호출.
+
+```js
+const lib = require('@angar2/taskery/bin/lib'); // 또는 패키지 내부 경로
+const blNum = await lib.appendBacklogItem(MAIN_WT, {
+  type: '<유형>',
+  title: '<제목>',
+  slug: '<슬러그>',
+  summary: '<개요>',
+  target: '<대상 영역>',
+});
+```
+
+내부 흐름:
+1. `withMetaLock(backlogPath)` 안에서:
+   - BACKLOG.md 전체에서 `BL-(\d+)` 패턴 grep → 최대값 + 1. 빈 파일 → BL-001 시작
+   - 항목 블록 포맷팅:
+     ```
+     - [ ] **BL-NNN** [유형] 제목 `slug`
+       - 개요: ...
+       - 대상 영역: ...
+     ```
+   - plan-init 빈 골격의 placeholder 라인 (`(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)`) 발견 시 → 그 자리에 치환. 미발견 시 → 파일 끝 빈 줄 + 블록 append
+
+### Step 6 — 결과 보고
+
+```
+✅ BL-<NNN> [<유형>] <제목> — <vX.X> 백로그 추가됐어.
+   - 개요: <개요>
+   - 대상 영역: <대상 영역>
+   - 슬러그: <slug>
+다음: 진행 의향이면 *"BL-<NNN> 진행"*이라고 말해. `/task-init`이 메타 그대로 받아 워크트리를 분기하고 항목을 `[x]` 확인 마킹할게.
+```
+
+## 도구 가이드
+
+- **Bash**: 메인 워크트리 검출 / dev 체크아웃 검증
+- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` (활성 버전 검출) / 기존 BACKLOG.md 정독 (중복 / 유사 항목 사전 확인)
+- **bin/lib.js**: `getActiveVersion` / `getBacklogPath` / `appendBacklogItem` 호출
+- **AskUserQuestion**: 유형 모호 시 confirm — 한 번에 한 질문
+
+## 주의사항
+
+- **얕은 분석만** — 본 스킬에서 도메인 코드 Read · Grep 금지. 본격 분석은 `/task-plan`
+- **유형 자동 추정 + 모호 시 confirm** — *"메뉴 검색 개선"* 같이 feature/improve 모호 시 사용자 결정 받기
+- **메인 워크트리 dev 검증 누락 X** — 위배 시 즉시 중단. 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md에 쓰기
+- **활성 버전 부재 시 즉시 중단** — `AGENT-GUIDE.md` 부재 / `## 활성 plan 버전` 섹션 부재 / vX.X 패턴 추출 실패 모두 명확한 에러 메시지 후 사용자 호출
+- **결정적 슬러그 best-effort** — LLM 비결정성 수용. race 차단 본체는 SSoT 2층(`/task-init` §4.4)이 담당. 슬러그 변형 발생 시 사용자 confirm
+- **글로벌 BACKLOG.md (plan 기획 후보)** 와 혼동 X — 본 스킬은 *버전별*만 다룸. 글로벌은 `/plan-init` 영역
+- **자동 추정 진행 X** — 유형 / 제목 / 개요 / 대상 영역 모두 사용자 OK 또는 명백한 발화 매칭 후에만 BACKLOG.md 쓰기
+
+## 상태 전이
+
+해당 없음 (백로그 메모지 누적 — task 상태 X).
+
+## 멀티세션 정합
+
+- **위치 = 메인 워크트리 절대 경로** — 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md를 단일 소스로 사용
+- **`withMetaLock` 직렬화** — 두 메인 세션이 동시 `/add-backlog` 호출 시 락으로 직렬화 (proper-lockfile, stale=30s, retries=5). 한 세션 `/add-backlog` + 다른 세션 `/task-init` (BL 마킹) 동시 시도 시 락 정합
+- **체크박스 의미** — `[ ]` = 미확인 (task로 옮기지 않은 메모) / `[x]` = 확인 완료 (task로 옮김). **dev 머지 완료 의미 X** — 완료 추적은 `git log dev --grep 'BL-NNN'` + 브랜치명 + `taskery status`

package/template/.claude/skills/log-friction/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: log-friction
+description: 사용자가 작업 흐름 중 겪은 불편(friction)을 .project/FRICTION_LOG.md에 한 행 기록한다. 사용자가 짜증·불만·답답함을 표현하면 자동 발동(등록 제안). 명시 호출(`/log-friction`) 또는 `/task-close` 직후 마찰 신호 자체 감지 시에도 발동한다.
+---
+
+# /log-friction
+
+## 개요
+
+사용자가 작업 흐름 중 겪은 불편을 `.project/FRICTION_LOG.md`에 한 행 기록한다.
+후속 조치 X — 분석 / 패턴 감지 / 룰 제안 자체를 본 스킬이 수행하지 않는다. 사용자가 직접 검토 후 판단한다.
+
+## 호출 시점 (3가지 트리거)
+
+1. **사용자 명시 호출** — `/log-friction "<불편 내용>"` 또는 인자 없이 호출
+2. **사용자 불만 발화 캐치** — 메인 세션이 사용자 발화에서 불편·짜증·답답함 신호를 감지하면 *"이거 FRICTION_LOG에 등록할까?"* 제안한 후 사용자 OK 시 자동 발동
+3. **task-close 직후 메인 자체 감지** — 작업 중 마찰 신호(동일 단계 재호출 / 실패 반복 / 사용자 부정 반응 누적 등)가 감지된 경우에만 *"이번 task에서 X 부분이 마찰이었어 보여 — 등록할까?"* 제안한 후 사용자 OK 시 발동. 감지 신호 없으면 호출 X
+
+## 입력 처리
+
+- 인자 형태 (사용자 명시 호출):
+  - `/log-friction "<불편 내용>"` — 큰따옴표 인자에 본문 직접 전달
+  - `/log-friction` — 인자 없이 호출 시 메인이 사용자에게 *"어떤 점이 불편했는지?"* 묻고 답변을 받음
+- 자동 발동 시: 메인이 캐치한 발화 또는 감지한 마찰 신호를 사용자에게 *확인 차원*으로 보여주고 등록 본문에 대해 합의를 받음
+
+## 단계
+
+### Step 1 — 호출 경로 확인
+
+호출 형태에 따라 분기한다.
+
+- 직접 호출 (인자 있음) → 인자 본문을 등록 후보로 사용
+- 직접 호출 (인자 없음) → 사용자에게 불편 내용을 질문
+- 자동 발동 (불만 발화 캐치) → 캐치한 발화를 등록 후보로 보여주고 사용자 합의
+- 자동 발동 (task-close 자체 감지) → 감지한 마찰 신호를 보여주고 사용자 합의
+
+### Step 2 — 등록 본문 확정
+
+사용자가 합의한 내용을 한 행(1~3 문장 이내)으로 정리한다.
+
+포맷:
+
+```
+- YYYY-MM-DD | <맥락 — TASK 번호 또는 호출 시점> | <불편 내용 요약>
+```
+
+### Step 3 — FRICTION_LOG.md 한 행 추가
+
+`.project/FRICTION_LOG.md`를 Read한 후 마지막 행 다음에 신규 행을 Append(Edit)한다.
+파일이 없거나 비어 있으면 안내 후 첫 행을 작성한다.
+
+### Step 4 — 결과 보고
+
+```
+✅ /log-friction 완료
+- 추가된 행: <등록 본문>
+- 누적 행 수: <N>건
+- 다음 호출: 사용자 명시 / 불만 발화 캐치 / task-close 자체 감지 중 하나
+```
+
+## 도구 가이드
+
+- **Read**: `.project/FRICTION_LOG.md` 정독
+- **Edit**: 마지막 행 다음에 신규 행 Append
+- **AskUserQuestion**: Step 1·2 사용자 합의
+
+## 주의사항
+
+- 본 스킬은 *기록 행위*만 수행한다. 패턴 분석 / PLAYBOOK 매핑 / 룰 제안 X.
+- task-close 자체 감지 트리거는 *마찰 신호 감지* 시에만 발동한다. 감지 없는 task-close에서 prompt 강제 X.
+- 사용자 합의 없이 자동 등록 X. 자동 발동 경로도 반드시 사용자 OK 후 기록한다.
+- 메인 자체 판단으로 등록 본문을 임의 가공·확장 X. 사용자 발화 또는 감지한 신호를 *그대로 인용* 원칙.
+
+## 상태 전이
+
+해당 없음 (meta 레벨 — task 상태 전이 X).

package/template/.claude/skills/{plan-init.md → plan-init/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: plan-init
 description: plan 버전 단위 9 기획 문서 작성 — 신규 vX.X/ 또는 기존 카피 후 변경 인터뷰
 ---
 
@@ -65,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와 일관).
@@ -83,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` 작성/갱신
 
@@ -118,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 문서별 핵심 질문 + 변경 인터뷰