@angar2/taskery 0.1.1 → 0.1.3

package/README.md

@@ -15,6 +15,7 @@ AI 코딩 에이전트의 자율 개발을 위한 Task 기반의 가드레일
 | 작업 컨텍스트가 휘발되어 이전 결정·사유를 추적하기 어려움 | task 문서로 컨텍스트와 히스토리 기록 — 작업 중 참조 가능 |
 | 에이전트가 catastrophic 사고를 일으킬 수 있음 | 필수 hook으로 차단 — 정상 흐름에는 무간섭 |
 | 에이전트가 작성한 코드의 자가검증으로 인해 문제를 놓침 (confirmation bias) | 테스트 시 별도 격리 세션 호출(`/task-test`) — 메인 세션의 가정 없이 독립 검증 |
+| 단일 메인 세션 운영으로 인해 task를 직렬로 진행해야 하는 병목 | 같은 프로젝트에서 여러 메인 세션이 독립 작업 폴더(worktree)로 병렬 진행 — 머지 시점에 직렬화로 정합성 유지 |
 
 > catastrophic 사고 예시 — git 운영 정책 위반, 검증 우회, 완료된 task 문서 재수정 등
 
@@ -46,7 +47,7 @@ draft → planned → developing → developed → testing → tested → closed
 
 ## 빠른 시작
 
-> **요구 사항**: Node.js ≥ 18.
+> **요구 사항**: Node.js ≥ 18, git ≥ 2.31 (멀티세션 워크트리 기능 사용 시).
 
 ### npx
 
@@ -62,6 +63,10 @@ npx @angar2/taskery init
 
 # 최신 버전 머지 갱신
 npx @angar2/taskery update
+
+# 멀티세션 보조 명령
+npx @angar2/taskery status   # 진행중 태스크 / 워크트리 / 머지 락 현황
+npx @angar2/taskery prune    # stale 워크트리 / 브랜치 대화형 정리
 ```
 
 ### 글로벌 npm install
@@ -80,6 +85,10 @@ taskery init
 
 # 최신 버전 머지 갱신
 taskery update
+
+# 멀티세션 보조 명령
+taskery status
+taskery prune
 ```
 
 ---
@@ -95,19 +104,22 @@ my-app/
 ├─ .gitignore
 ├─ .claude/
 │   ├─ settings.json                      # hook 등록 (PreToolUse 매칭)
-│   ├─ skills/<skil-name>/SKILL.md        # 8 skill
-│   └─ hooks/<hook-name>.sh               # 3 hook
+│   ├─ skills/<skill-name>/SKILL.md       # 9 skill
+│   └─ hooks/<hook-name>.sh               # 2 hook
 └─ .project/
     ├─ PROJECT.md                         # 프로젝트 개요
     ├─ AGENT-GUIDE.md                     # AI 에이전트 가이드
     ├─ LINKED-REPOS.md                    # 관계 리포지토리 정보
+    ├─ GLOSSARY.md                        # 도메인 용어집 (영문/한글 표기 일관성)
     ├─ .env                               # 사용자 설정 환경변수 (관계 리포지토리 환경변수 등)
     ├─ rules/
     │   ├─ TASK_DOC_RULE.md               # task 문서 작성 규칙
     │   ├─ GIT_RULE.md                    # 로컬 깃 운영 규칙
+    │   ├─ CHANGELOG_RULE.md              # CHANGELOG 작성 규칙
+    │   ├─ MOCKUP_RULE.md                 # UX/UI HTML 목업 규칙
     │   └─ *.local.md                     # 사용자 오버라이드 규칙 (패키지 업데이트 대상 제외)
     ├─ plans/                             # plan 문서
-    ├─ tasks/                             # task 문서
+    ├─ tasks/                             # task 문서 (vX.X/BACKLOG.md / spec-diffs / screenshots / mockup 포함)
     ├─ flows/                             # 서비스 로직 플로우 정보
     ├─ changelog/                         # 수정사항 정보
     ├─ shared/                            # 관계 리포지토리 소통 메세지함
@@ -118,6 +130,30 @@ my-app/
 
 ---
 
+## 멀티세션 (병렬 작업)
+
+같은 프로젝트에서 여러 메인 세션을 동시에 운영해 독립 task를 병렬로 진행한다.
+
+- 새 task를 시작하면(`/task-init`) 작업 폴더(`~/.taskery/worktrees/<projectId>/TASK-NNN_<출처>_<슬러그>/`)와 작업 브랜치를 함께 분기한다.
+- 작업 폴더에서 새 메인 세션을 열어 진행하거나, 메인 세션 1개로 모든 작업을 지휘하거나, 메인이 서브 세션을 호출해 병렬로 진행한다 — 운영 방식은 자유. 메인 워크트리(원본 폴더)는 `dev` 전용 상태로 유지된다.
+- task 완료(`/task-close`) 시 머지 락으로 직렬화한 후 dev에 `--no-ff` 병합한다. 다른 세션이 먼저 머지해 충돌이 발생하면 본 세션이 단순/의미적/판단 불가 3단계로 해결을 시도한다.
+- 머지 직후 작업 폴더와 작업 브랜치는 자동 정리된다(보존 키워드 사용 시 양쪽 유지). 안전망으로 복구 명령이 함께 출력된다.
+
+요건: git ≥ 2.31. 보조 명령 `npx @angar2/taskery status` / `prune`로 진행 현황과 stale 정리를 확인한다.
+
+---
+
+## 백로그 메모
+
+작업 흐름 중 발견되는 추가 기능과 버그를 *그 자리에서 짧게 적어 둔다*. 메인 세션이 사용자 발화를 받아 `/add-backlog`로 1건씩 활성 plan 버전의 `tasks/<vX.X>/BACKLOG.md`에 누적한다.
+
+- 항목 형식: 체크박스 + 식별자(BL-NNN) + 유형 + 제목 + 슬러그. 그 아래 *개요*(추정 원인 / 구상)와 *대상 영역*(관여할 파일·모듈) 2줄.
+- 시작 시점: 사용자가 *"BL-NNN 진행"*이라고 말하면 `/task-init`이 그 항목 메타로 task를 분기하고 BACKLOG.md 항목을 *확인* 마킹(`[x]`)하며 `- TASK: TASK-NNN`을 함께 남긴다. *완료*가 아니라 *task로 옮겼다*는 의미만 담는다.
+- 완료 추적: git 머지 히스토리와 `taskery status`. BACKLOG.md는 메모지 역할만 한다.
+- plan 후보 카탈로그(글로벌 `.project/BACKLOG.md`)는 다음 plan 버전 기획용으로 분리 관리한다.
+
+---
+
 ## Skills
 
 스킬은 호출 시점에 따라 4 카테고리(`project` / `plan` / `task` / `meta`)로 분류된다.
@@ -136,6 +172,7 @@ my-app/
 | `/task-dev` | task | 계획에 따른 단계별 구현 + 자가 검증 |
 | `/task-test` | task | 별도 격리 세션에서 독립 검증 (메인 가정 차단) |
 | `/task-close` | task | 최종 검증 후 git 커밋 + dev 브랜치 `--no-ff` 병합 |
+| `/add-backlog` | meta | 사용자 발화로 버전별 `tasks/<vX.X>/BACKLOG.md`에 task 후보 1건씩 추가 (0.1.2+) |
 | `/log-friction` | meta | 사용자 불편을 `.project/FRICTION_LOG.md`에 한 행 기록 |
 
 각 스킬은 슬래시로 직접 호출하거나, 사용자 발화의 의미가 스킬의 frontmatter description과 매칭되면 메인 세션이 자동으로 발동시킨다.
@@ -157,7 +194,6 @@ my-app/
 | Hook | 작동 시점 | 차단 대상 |
 |------|---------|---------|
 | `git-guard.sh` | git 명령 실행 직전 | 주력 브랜치 직접 커밋 / `--force` / `--no-verify` / 강제 브랜치 삭제 / `reset --hard` / `clean -fd` |
-| `pre-commit-verify.sh` | `git commit` 실행 직전 | 검증 명령(린트·타입체크·빌드·테스트) 통과 실패 commit |
 | `closed-immutable.sh` | 파일 수정 직전 | 완료(`closed`)된 task.md 본 파일 재수정 (관련 spec-diff·스크린샷은 자유) |
 
 hook은 catastrophic 사고만 차단한다. 정상 흐름에는 간섭하지 않는다.
@@ -193,6 +229,7 @@ npx @angar2/taskery init
 
 - *"로그인 기능 추가해줘"* / *"이 버그 고쳐줘"* → `/task-init` 자동 발동 (새 task 시작 의도)
 - *"기획 다 됐으니 이제 구현 시작해"* → `/task-dev` 자동 발동 (planned task의 다음 단계)
+- *"이 부분도 백로그에 추가해줘"* / *"나중에 할 일로 적어둬"* → `/add-backlog` 자동 발동 (백로그 추가 의도)
 - *"이거 진짜 불편하다"* / *"이 부분 답답하네"* → `/log-friction` 자동 발동 (불만 발화 캐치)
 
 **실패·불확정 분기** — `/task-test`가 FAIL 또는 UNCERTAIN을 반환하면 메인 세션이 사용자에게 판단을 묻고, 사용자의 자연어 답변에서 의도를 해석해 다음 흐름을 *자동 발동*한다(별도 슬래시 호출 없이 진행됨).
@@ -208,9 +245,9 @@ npx @angar2/taskery init
 spec 문서는 GitHub에서 참고할 수 있다.
 
 - [OVERVIEW.md](https://github.com/angar2/taskery/blob/main/plan/OVERVIEW.md) — 시스템 진입 가이드와 전체 구조 개요.
-- [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md) — 스킬 8종의 상세 명세와 호출 흐름.
+- [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md) — 스킬 9종의 상세 명세와 호출 흐름.
 - [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md) — task 문서의 작성 양식과 7 상태 머신의 동작 정의.
-- [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md) — catastrophic hook 3종의 정책과 예외 처리 절차.
+- [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md) — catastrophic hook 2종의 정책과 예외 처리 절차.
 - [DISTRIBUTION.md](https://github.com/angar2/taskery/blob/main/plan/DISTRIBUTION.md) — npx 배포 메커니즘과 자산 갱신 로직.
 - [DECISIONS.md](https://github.com/angar2/taskery/blob/main/plan/DECISIONS.md) — 시스템 설계의 핵심 의사결정과 변경 이력.
 - [PLAYBOOK.md](https://github.com/angar2/taskery/blob/main/plan/PLAYBOOK.md) — 향후 도입 가능한 기능 후보 목록.

package/bin/init.js

@@ -7,7 +7,7 @@
  *   1. cwd에 .taskery-manifest.json 이미 있으면 경고 + confirm
  *   2. template/ 안 *모든 파일* cwd로 카피 (디렉토리 자동 생성)
  *   3. *.local.md 사용자 오버라이드 충돌 검사 (덮어쓰지 X)
- *   4. .taskery-manifest.json 박음 (version + installed_at + files{path,hash,core,managed} 맵)
+ *   4. .taskery-manifest.json 작성 (version + installed_at + files{path,hash,core,managed} 맵)
  *   5. 결과 요약 출력 + 다음 단계 안내 (`/project-init`)
  */
 
@@ -24,6 +24,9 @@ const {
   readManifest,
   getPackageVersion,
   isLocalOverride,
+  generateProjectId,
+  DEFAULT_STALE_DAYS,
+  DEFAULT_LOCK_TIMEOUT_MS,
 } = require('./lib');
 
 async function confirm(msg) {
@@ -93,14 +96,54 @@ async function main() {
     console.log(`  copy: ${rel}`);
   }
 
-  // 4. manifest 박음
+  // 4. manifest 작성 — 멀티세션(0.1.2+): projectId / stale_days / lock_timeout_ms 포함
   const manifest = {
     version: getPackageVersion(),
     installed_at: new Date().toISOString(),
+    projectId: generateProjectId(),
+    stale_days: DEFAULT_STALE_DAYS,
+    lock_timeout_ms: DEFAULT_LOCK_TIMEOUT_MS,
     files: manifestFiles,
   };
   writeManifest(manifest, manifestPath);
 
+  // 4.5. .gitignore prompt (stash FRICTION_LOG #26 반영)
+  //   공개 repo면 내부 워크플로 파일 노출 회피 — taskery 내부 영역 .gitignore 등록 제안.
+  //   사용자 NO면 패스 (그대로 둠). 이미 등록되어 있으면 스킵.
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const taskeryPatterns = [
+    '.project/',
+    '.claude/',
+    'CLAUDE.md',
+    '.taskery-manifest.json',
+  ];
+  const addGitignore = await confirm(
+    `\ntaskery 내부 파일(.project/, .claude/, CLAUDE.md, .taskery-manifest.json)을 .gitignore에 등록할까?\n  (공개 repo면 권장 — 내부 워크플로 파일 노출 회피)`,
+  );
+  if (addGitignore) {
+    const existing = fs.existsSync(gitignorePath)
+      ? fs.readFileSync(gitignorePath, 'utf8').split('\n')
+      : [];
+    const existingSet = new Set(existing.map((l) => l.trim()));
+    const newPatterns = taskeryPatterns.filter((p) => !existingSet.has(p));
+    if (newPatterns.length > 0) {
+      const needsLeadingNewline =
+        existing.length > 0 && existing[existing.length - 1] !== '';
+      const block = [
+        needsLeadingNewline ? '' : null,
+        '# taskery 내부 파일',
+        ...newPatterns,
+        '',
+      ].filter((l) => l !== null);
+      fs.appendFileSync(gitignorePath, block.join('\n'));
+      console.log(`  .gitignore 갱신 — ${newPatterns.length}개 패턴 추가`);
+    } else {
+      console.log(`  .gitignore — taskery 패턴 이미 등록됨, 스킵`);
+    }
+  } else {
+    console.log(`  .gitignore — 사용자 선택으로 패스`);
+  }
+
   // 5. 결과 보고
   console.log(`\n✅ taskery init 완료`);
   console.log(`   카피: ${copied}개 / 스킵: ${skipped}개`);

package/bin/lib.js

@@ -1,6 +1,6 @@
 /**
  * bin/lib.js
- * 공통 유틸 — taskery init/create/update 스크립트가 공유.
+ * 공통 유틸 — taskery init/create/update/prune/status 스크립트가 공유.
  *
  * 핵심:
  *   - findTemplateDir(): 패키지 설치 위치에서 template/ 디렉토리 찾기
@@ -8,14 +8,37 @@
  *   - sha256(path): 파일 해시
  *   - mkdirp(path): mkdir -p
  *   - copyFile(src, dst): 파일 카피 + 디렉토리 자동 생성
- *   - writeManifest(manifest, dst): manifest JSON 박음
+ *   - writeManifest(manifest, dst): manifest JSON 기록
  *   - readManifest(path): 기존 manifest Read (없으면 null)
  *   - LOCAL_SUFFIX: '.local.md' suffix 검사 (npx 미터치 룰)
+ *
+ * 멀티세션 (0.1.2+):
+ *   - generateProjectId(): 새 projectId 생성 (8자 hex)
+ *   - getMainWorktreePath(cwd): cwd가 속한 git 트리의 *메인 워크트리* 절대 경로
+ *   - getProjectId(mainWtPath): manifest에서 projectId 추출
+ *   - getWorktreesRoot(projectId): ~/.taskery/worktrees/<projectId>
+ *   - getWorktreePath(projectId, { taskNum, src, slug }): 특정 task 워크트리 경로
+ *   - getMergeLockPath(projectId): ~/.taskery/<projectId>.merge.lock
+ *   - withMergeLock(projectId, fn, opts): proper-lockfile로 머지 락 + fn 실행 + 자동 release
+ *   - withMetaLock(filePath, fn, opts): 메타 파일 쓰기 락 + fn 실행
+ *   - getActiveTasks(mainWtPath): SSoT 조회 (git branch --no-merged dev --list 'feature/*_TASK-*' ...)
+ *   - getNextTaskNumber(mainWtPath): (진행중 ∪ dev 머지 히스토리) 최대 + 1
+ *   - assertMainWorktreeOnDev(mainWtPath): 메인 워크트리가 dev 체크아웃 상태인지 검증
+ *   - assertDevExists(mainWtPath): dev 브랜치 존재 검증
+ *
+ * 백로그 (0.1.2+):
+ *   - getActiveVersion(mainWtPath): .project/AGENT-GUIDE.md에서 활성 plan 버전(vX.X) 추출
+ *   - getBacklogPath(mainWtPath, activeVersion?): .project/tasks/<vX.X>/BACKLOG.md 절대 경로
+ *   - parseBacklogItem(mainWtPath, blId): BL-NNN 항목 메타 파싱 ({ status, type, title, slug, summary, target, taskNums })
+ *   - appendBacklogItem(mainWtPath, meta): withMetaLock + BL-NNN 채번 + 항목 append (placeholder 치환 우선)
+ *   - markBacklogChecked(mainWtPath, blId, taskNum): withMetaLock + [ ] → [x] + TASK 마크 (다회 진행 시 콤마 추가)
  */
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 
 const LOCAL_SUFFIX = '.local.md';
 const MANIFEST_NAME = '.taskery-manifest.json';
@@ -92,6 +115,349 @@ function getPackageVersion() {
   return pkg.version;
 }
 
+// === 멀티세션 (0.1.2+) ===
+
+const TASKERY_HOME = path.join(os.homedir(), '.taskery');
+const DEFAULT_STALE_DAYS = 30;
+const DEFAULT_LOCK_TIMEOUT_MS = 30000;
+
+const BRANCH_PATTERNS = [
+  'feature/*_TASK-*',
+  'bug/*_TASK-*',
+  'improve/*_TASK-*',
+  'refactor/*_TASK-*',
+  'docs/*_TASK-*',
+  'chore/*_TASK-*',
+];
+
+function generateProjectId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+function gitCapture(cwd, args, opts = {}) {
+  try {
+    return execFileSync('git', ['-C', cwd, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', opts.captureStderr ? 'pipe' : 'ignore'],
+    }).trimEnd();
+  } catch (e) {
+    if (opts.allowFail) return null;
+    throw e;
+  }
+}
+
+function getMainWorktreePath(cwd = process.cwd()) {
+  // git ≥ 2.31 — `git rev-parse --path-format=absolute --git-common-dir` 는
+  // 메인 워크트리의 .git 경로(또는 .git 디렉토리 자체)를 절대 경로로 돌려준다.
+  // 그 부모가 *메인 워크트리* 절대 경로.
+  const commonDir = gitCapture(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!commonDir) throw new Error(`메인 워크트리 검출 실패 (cwd=${cwd})`);
+  return path.dirname(commonDir);
+}
+
+function getProjectId(mainWtPath) {
+  const m = readManifest(path.join(mainWtPath, MANIFEST_NAME));
+  if (!m || !m.projectId) {
+    throw new Error(
+      `${MANIFEST_NAME}.projectId 누락 — 'npx @angar2/taskery update' 로 마이그레이션 필요.`,
+    );
+  }
+  return m.projectId;
+}
+
+function getWorktreesRoot(projectId) {
+  return path.join(TASKERY_HOME, 'worktrees', projectId);
+}
+
+function getWorktreePath(projectId, { taskNum, src, slug }) {
+  // src = 'BL-NNN' | 'RM-NNN' | 'DR'
+  const nnn = String(taskNum).padStart(3, '0');
+  return path.join(getWorktreesRoot(projectId), `TASK-${nnn}_${src}_${slug}`);
+}
+
+function getMergeLockPath(projectId) {
+  return path.join(TASKERY_HOME, `${projectId}.merge.lock`);
+}
+
+async function withMergeLock(projectId, fn, opts = {}) {
+  const lockfile = require('proper-lockfile');
+  const lockPath = getMergeLockPath(projectId);
+  mkdirp(path.dirname(lockPath));
+  // proper-lockfile은 *기존 파일 위에 락*을 잡는다. sentinel 파일 보장.
+  if (!fs.existsSync(lockPath)) fs.writeFileSync(lockPath, '');
+  const release = await lockfile.lock(lockPath, {
+    stale: opts.stale ?? DEFAULT_LOCK_TIMEOUT_MS,
+    retries: opts.retries ?? {
+      retries: 5,
+      factor: 1,
+      minTimeout: 1000,
+      maxTimeout: 1000,
+    },
+    realpath: false,
+  });
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+async function withMetaLock(filePath, fn, opts = {}) {
+  const lockfile = require('proper-lockfile');
+  const target = filePath;
+  if (!fs.existsSync(target)) {
+    // 락 대상은 파일이어야 함. 없으면 sentinel 빈 파일 만들어 락 가능 상태로.
+    mkdirp(path.dirname(target));
+    fs.writeFileSync(target, '');
+  }
+  const release = await lockfile.lock(target, {
+    stale: opts.stale ?? DEFAULT_LOCK_TIMEOUT_MS,
+    retries: opts.retries ?? {
+      retries: 5,
+      factor: 1,
+      minTimeout: 1000,
+      maxTimeout: 1000,
+    },
+    realpath: false,
+  });
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+function assertDevExists(mainWtPath) {
+  const ok = gitCapture(mainWtPath, ['rev-parse', '--verify', 'dev'], { allowFail: true });
+  if (ok === null) {
+    throw new Error('dev 브랜치 부재. 사용자 결정 필요 (생성?).');
+  }
+}
+
+function assertMainWorktreeOnDev(mainWtPath) {
+  const current = gitCapture(mainWtPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (current !== 'dev') {
+    throw new Error(`메인 워크트리가 dev 아님 (현재: ${current}). taskery 정책 위배.`);
+  }
+}
+
+function parseBranchName(branch) {
+  // 형식: {type}/{dev}_TASK-NNN_{src}_{slug}
+  // 예: feature/claude_TASK-007_BL-003_login-feature
+  //     bug/angar2_TASK-012_DR_mobile-form-refresh
+  const m = branch.match(
+    /^(feature|bug|improve|refactor|docs|chore)\/([^_]+)_TASK-(\d+)_([A-Z]{2}(?:-\d+)?|DR)_(.+)$/,
+  );
+  if (!m) return null;
+  return {
+    branch,
+    type: m[1],
+    dev: m[2],
+    taskNum: parseInt(m[3], 10),
+    src: m[4],
+    slug: m[5],
+  };
+}
+
+function getActiveTasks(mainWtPath) {
+  // SSoT — TASK-* 패턴 작업 브랜치 (분기 직후 빈 브랜치 포함). `--no-merged dev` 미사용:
+  // 워크트리 분기 직후 브랜치는 dev와 동일 commit이라 `--no-merged dev`가 *완전 머지 상태*로
+  // 처리 → 빈 결과 → getNextTaskNumber 충돌. 브랜치 존재 자체가 SSoT (정상 흐름은 task-close
+  // 자동 삭제로 자연 정리, 보존 키워드 잔존분도 *진행중*으로 잡힘이 정합).
+  const out = gitCapture(mainWtPath, ['branch', '--list', ...BRANCH_PATTERNS]);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .map((l) => l.replace(/^[*+]?\s*/, '').trim())
+    .filter(Boolean)
+    .map(parseBranchName)
+    .filter(Boolean);
+}
+
+function getNextTaskNumber(mainWtPath) {
+  // 1. 진행중 (SSoT)
+  const activeNums = getActiveTasks(mainWtPath).map((t) => t.taskNum);
+  // 2. dev 머지 히스토리 (GIT_RULE 풍부 메시지)
+  const log = gitCapture(mainWtPath, [
+    'log',
+    'dev',
+    '--grep',
+    'TASK-[0-9]\\+',
+    '--extended-regexp',
+    '--oneline',
+  ]);
+  const merged = log
+    ? Array.from(log.matchAll(/TASK-(\d+)/g)).map((m) => parseInt(m[1], 10))
+    : [];
+  const all = [...activeNums, ...merged];
+  if (all.length === 0) return 1;
+  return Math.max(...all) + 1;
+}
+
+// ─── 백로그 (0.1.2+) ────────────────────────────────────────────────
+
+const BACKLOG_PLACEHOLDER =
+  '(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)';
+
+function getActiveVersion(mainWtPath) {
+  // .project/AGENT-GUIDE.md '## 활성 plan 버전' 섹션 다음 비어 있지 않은 첫 줄에서 vX.X 추출
+  const guidePath = path.join(mainWtPath, '.project', 'AGENT-GUIDE.md');
+  if (!fs.existsSync(guidePath)) {
+    throw new Error(`.project/AGENT-GUIDE.md 부재. /project-init 먼저 호출.`);
+  }
+  const content = fs.readFileSync(guidePath, 'utf8');
+  const sec = content.match(/##\s*활성 plan 버전\s*\n+([^\n]+)/);
+  if (!sec) {
+    throw new Error(`.project/AGENT-GUIDE.md '## 활성 plan 버전' 섹션 부재.`);
+  }
+  const m = sec[1].match(/\bv[\d.]+(?:[-\w]*)?/);
+  if (!m) {
+    throw new Error(
+      `'## 활성 plan 버전' 값에서 vX.X 패턴 추출 실패: ${sec[1].trim()} — /plan-init으로 활성 버전 갱신 필요.`,
+    );
+  }
+  return m[0];
+}
+
+function getBacklogPath(mainWtPath, activeVersion) {
+  const v = activeVersion ?? getActiveVersion(mainWtPath);
+  return path.join(mainWtPath, '.project', 'tasks', v, 'BACKLOG.md');
+}
+
+function computeNextBLNumber(content) {
+  const matches = Array.from(content.matchAll(/\bBL-(\d+)\b/g)).map((m) => parseInt(m[1], 10));
+  if (matches.length === 0) return 1;
+  return Math.max(...matches) + 1;
+}
+
+function formatBacklogBlock({ id, type, title, slug, summary, target }) {
+  const blId = `BL-${String(id).padStart(3, '0')}`;
+  return `- [ ] **${blId}** [${type}] ${title} \`${slug}\`\n  - 개요: ${summary}\n  - 대상 영역: ${target}`;
+}
+
+async function appendBacklogItem(mainWtPath, meta) {
+  // meta: { type, title, slug, summary, target }
+  const backlogPath = getBacklogPath(mainWtPath);
+  if (!fs.existsSync(backlogPath)) {
+    throw new Error(
+      `${backlogPath} 부재. /plan-init 먼저 호출해 활성 버전 디렉토리 + 빈 BACKLOG.md 생성 필요.`,
+    );
+  }
+  return await withMetaLock(backlogPath, async () => {
+    const content = fs.readFileSync(backlogPath, 'utf8');
+    const next = computeNextBLNumber(content);
+    const block = formatBacklogBlock({ id: next, ...meta });
+    let updated;
+    if (content.includes(BACKLOG_PLACEHOLDER)) {
+      updated = content.replace(BACKLOG_PLACEHOLDER, block);
+    } else {
+      updated = content.replace(/\s*$/, '') + '\n\n' + block + '\n';
+    }
+    fs.writeFileSync(backlogPath, updated);
+    return next;
+  });
+}
+
+function parseBacklogItem(mainWtPath, blId) {
+  // blId: 'BL-001'. 발견 못하면 null.
+  const backlogPath = getBacklogPath(mainWtPath);
+  if (!fs.existsSync(backlogPath)) return null;
+  const content = fs.readFileSync(backlogPath, 'utf8');
+  const lines = content.split('\n');
+  const headRe = new RegExp(
+    `^- \\[([ x])\\] \\*\\*${blId}\\*\\* \\[(\\w+)\\] (.+?) \`([\\w-]+)\``,
+  );
+  let idx = -1;
+  let head = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(headRe);
+    if (m) {
+      idx = i;
+      head = m;
+      break;
+    }
+  }
+  if (idx === -1) return null;
+  let summary = null;
+  let target = null;
+  let taskNums = null;
+  for (let j = idx + 1; j < lines.length; j++) {
+    const l = lines[j];
+    if (l.startsWith('- ') && !l.startsWith('  - ')) break; // 다음 BL 항목
+    if (l.trim() === '') continue; // 블록 안 빈 줄 허용 (안전)
+    if (!l.startsWith('  - ')) break;
+    const ms = l.match(/^  - 개요:\s*(.+)/);
+    if (ms) { summary = ms[1].trim(); continue; }
+    const mt = l.match(/^  - 대상 영역:\s*(.+)/);
+    if (mt) { target = mt[1].trim(); continue; }
+    const mk = l.match(/^  - TASK:\s*(.+)/);
+    if (mk) { taskNums = mk[1].trim(); continue; }
+  }
+  return {
+    blId,
+    status: head[1] === 'x' ? 'checked' : 'pending',
+    type: head[2],
+    title: head[3],
+    slug: head[4],
+    summary,
+    target,
+    taskNums,
+  };
+}
+
+async function markBacklogChecked(mainWtPath, blId, taskNum) {
+  // taskNum: number. [ ] → [x] + TASK 마크 (있으면 콤마 추가, 없으면 신규 줄)
+  const backlogPath = getBacklogPath(mainWtPath);
+  if (!fs.existsSync(backlogPath)) {
+    throw new Error(`${backlogPath} 부재.`);
+  }
+  const taskLabel = `TASK-${String(taskNum).padStart(3, '0')}`;
+  return await withMetaLock(backlogPath, async () => {
+    const content = fs.readFileSync(backlogPath, 'utf8');
+    const lines = content.split('\n');
+    const headRe = new RegExp(`^(- )\\[[ x]\\](\\s+\\*\\*${blId}\\*\\*.+)$`);
+    let idx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (headRe.test(lines[i])) {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) {
+      throw new Error(`${blId} 항목 없음.`);
+    }
+    lines[idx] = lines[idx].replace(headRe, '$1[x]$2');
+    // 다음 BL 헤드 또는 파일 끝까지가 같은 블록 — 그 안에서 TASK 줄 검색
+    let blockEnd = lines.length;
+    for (let j = idx + 1; j < lines.length; j++) {
+      if (lines[j].startsWith('- ') && !lines[j].startsWith('  - ')) {
+        blockEnd = j;
+        break;
+      }
+    }
+    let taskLineIdx = -1;
+    for (let j = idx + 1; j < blockEnd; j++) {
+      if (lines[j].match(/^  - TASK:/)) {
+        taskLineIdx = j;
+        break;
+      }
+    }
+    if (taskLineIdx !== -1) {
+      const existing = lines[taskLineIdx].match(/^  - TASK:\s*(.+)/)[1].trim();
+      const existingTasks = existing.split(/[,\s]+/).filter(Boolean);
+      if (!existingTasks.includes(taskLabel)) {
+        lines[taskLineIdx] = `  - TASK: ${existing}, ${taskLabel}`;
+      }
+    } else {
+      // blockEnd 직전 빈 줄 건너뛰고 삽입
+      let insertAt = blockEnd;
+      while (insertAt > idx + 1 && lines[insertAt - 1].trim() === '') insertAt--;
+      lines.splice(insertAt, 0, `  - TASK: ${taskLabel}`);
+    }
+    fs.writeFileSync(backlogPath, lines.join('\n'));
+  });
+}
+
 module.exports = {
   LOCAL_SUFFIX,
   MANIFEST_NAME,
@@ -104,4 +470,32 @@ module.exports = {
   readManifest,
   isLocalOverride,
   getPackageVersion,
+  // 멀티세션 (0.1.2+)
+  TASKERY_HOME,
+  DEFAULT_STALE_DAYS,
+  DEFAULT_LOCK_TIMEOUT_MS,
+  BRANCH_PATTERNS,
+  generateProjectId,
+  gitCapture,
+  getMainWorktreePath,
+  getProjectId,
+  getWorktreesRoot,
+  getWorktreePath,
+  getMergeLockPath,
+  withMergeLock,
+  withMetaLock,
+  assertDevExists,
+  assertMainWorktreeOnDev,
+  parseBranchName,
+  getActiveTasks,
+  getNextTaskNumber,
+  // 백로그 (0.1.2+)
+  BACKLOG_PLACEHOLDER,
+  getActiveVersion,
+  getBacklogPath,
+  computeNextBLNumber,
+  formatBacklogBlock,
+  appendBacklogItem,
+  parseBacklogItem,
+  markBacklogChecked,
 };