@angar2/taskery 0.1.1 → 0.1.2

package/bin/prune.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * bin/prune.js
+ * `npx @angar2/taskery prune` — stale 워크트리 / 브랜치 대화형 정리.
+ *
+ * 흐름:
+ *   1. git worktree prune (자동, 케이스 A 폴더 없는 등록 정리)
+ *   2. 의심 항목 목록 표시 (케이스 B/C/D + orphan)
+ *   3. 사용자 항목별 보존 / 삭제 선택
+ *   4. 선택된 항목 삭제:
+ *      - 브랜치: git branch -D <name>  ← 사용자 명시 선택이므로 -D 허용 (rebase 잔여 등 -d 거부 가능)
+ *      - 워크트리: git worktree remove --force <path>
+ *   5. 결과 보고
+ *
+ * 본 명령은 *변경 발생 가능* — 사용자 confirm 항목별로 받음.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  gitCapture,
+  getMainWorktreePath,
+  getActiveTasks,
+  getWorktreesRoot,
+  DEFAULT_STALE_DAYS,
+} = require('./lib');
+const { execFileSync } = require('child_process');
+
+function ask(rl, q) {
+  return new Promise((resolve) => rl.question(q, (a) => resolve(a.trim().toLowerCase())));
+}
+
+function daysAgo(date) {
+  return Math.floor((Date.now() - date.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+async function main() {
+  const mainWt = getMainWorktreePath();
+  const manifest = readManifest(path.join(mainWt, MANIFEST_NAME));
+  if (!manifest) {
+    console.error(`${MANIFEST_NAME} 없음 — 'init' 먼저.`);
+    process.exit(1);
+  }
+  const projectId = manifest.projectId;
+  const staleDays = manifest.stale_days ?? DEFAULT_STALE_DAYS;
+
+  console.log(`\ntaskery prune\n`);
+  console.log(`메인 워크트리: ${mainWt}`);
+  console.log(`stale_days: ${staleDays}\n`);
+
+  // 1. git worktree prune (자동 — 케이스 A)
+  console.log(`Step 1 — git worktree prune (폴더 없는 워크트리 등록 정리)`);
+  try {
+    execFileSync('git', ['-C', mainWt, 'worktree', 'prune', '-v'], { stdio: 'inherit' });
+  } catch (e) {
+    console.error(`  git worktree prune 실패: ${e.message}`);
+  }
+  console.log();
+
+  // 2. 의심 항목 수집
+  const active = getActiveTasks(mainWt);
+  const worktreesRoot = getWorktreesRoot(projectId);
+
+  // 케이스 B/C/D
+  const suspects = [];
+  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 days = lastDate ? daysAgo(lastDate) : null;
+
+    let kase = null;
+    if (!wtExists) kase = 'A (폴더 없음 — git worktree prune 처리됐을 가능성)';
+    else if (days !== null && days >= staleDays) kase = `C (워크트리 폴더 존재 + ${days}일 비활성)`;
+
+    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)) {
+        kase = `D (rebase 잔여 상태)`;
+      }
+    }
+
+    if (kase) {
+      suspects.push({ branch: t.branch, wtPath, wtExists, days, kase });
+    }
+  }
+
+  // orphan 워크트리 (SSoT에 없는 폴더)
+  const orphans = [];
+  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}`,
+      ),
+    );
+    for (const f of folders) {
+      if (!activeFolders.has(f)) {
+        orphans.push(path.join(worktreesRoot, f));
+      }
+    }
+  }
+
+  if (suspects.length === 0 && orphans.length === 0) {
+    console.log(`✅ 정리할 의심 항목 없음.`);
+    return;
+  }
+
+  console.log(`Step 2 — 의심 항목 (${suspects.length + orphans.length}건)\n`);
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const toDelete = { branches: [], worktrees: [] };
+
+  // suspects 처리
+  for (const s of suspects) {
+    console.log(`[${s.kase}] ${s.branch}`);
+    console.log(`  워크트리: ${s.wtPath}${s.wtExists ? '' : ' (폴더 X)'}`);
+    if (s.days !== null) console.log(`  마지막 커밋: ${s.days}일 전`);
+    const ans = await ask(rl, `  삭제? (y=브랜치+워크트리 / w=워크트리만 / k=보존, 기본 k) `);
+    if (ans === 'y') {
+      toDelete.branches.push(s.branch);
+      if (s.wtExists) toDelete.worktrees.push(s.wtPath);
+    } else if (ans === 'w' && s.wtExists) {
+      toDelete.worktrees.push(s.wtPath);
+    } else {
+      console.log(`  보존`);
+    }
+    console.log();
+  }
+
+  // orphan 처리
+  for (const o of orphans) {
+    console.log(`[orphan] 워크트리 폴더 (SSoT에 없는 브랜치)`);
+    console.log(`  ${o}`);
+    const ans = await ask(rl, `  워크트리 폴더 삭제? (y/N) `);
+    if (ans === 'y') toDelete.worktrees.push(o);
+    else console.log(`  보존`);
+    console.log();
+  }
+
+  rl.close();
+
+  // 3. 실제 삭제
+  if (toDelete.branches.length === 0 && toDelete.worktrees.length === 0) {
+    console.log(`삭제 대상 없음.`);
+    return;
+  }
+
+  console.log(`\nStep 3 — 삭제 실행\n`);
+
+  for (const wt of toDelete.worktrees) {
+    try {
+      execFileSync('git', ['-C', mainWt, 'worktree', 'remove', '--force', wt], {
+        stdio: 'inherit',
+      });
+      console.log(`  worktree removed: ${wt}`);
+    } catch (e) {
+      console.error(`  worktree remove 실패 (${wt}): ${e.message}`);
+    }
+  }
+
+  for (const b of toDelete.branches) {
+    try {
+      // -D 강제 삭제 — 사용자 명시 선택 (prune 대화형) 이므로 허용
+      execFileSync('git', ['-C', mainWt, 'branch', '-D', b], { stdio: 'inherit' });
+      console.log(`  branch deleted: ${b}`);
+    } catch (e) {
+      console.error(`  branch -D 실패 (${b}): ${e.message}`);
+    }
+  }
+
+  console.log(`\n✅ taskery prune 완료 — 워크트리 ${toDelete.worktrees.length}건 / 브랜치 ${toDelete.branches.length}건 삭제.`);
+}
+
+main().catch((e) => {
+  console.error(`taskery prune 실패: ${e.message}`);
+  process.exit(1);
+});

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.1",
-  "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`