@angar2/taskery 0.8.1 → 1.0.1

package/bin/lib.js

@@ -1,1485 +1,740 @@
-/**
- * bin/lib.js
- * 공통 유틸 — taskery init/create/update/prune/status 스크립트가 공유.
- *
- * 핵심:
- *   - findTemplateDir(): 패키지 설치 위치에서 template/ 디렉토리 찾기
- *   - walkTemplate(templateDir): template/ 안 *모든 파일* 상대경로 + 해시 맵 리턴
- *   - sha256(path): 파일 해시
- *   - mkdirp(path): mkdir -p
- *   - copyFile(src, dst): 파일 카피 + 디렉토리 자동 생성
- *   - 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
- *   - getInitLockPath(projectId): ~/.taskery/<projectId>.init.lock (task 분기 직렬화용)
- *   - withMergeLock(projectId, fn, opts): proper-lockfile로 머지 락 + fn 실행 + 자동 release
- *   - withMetaLock(filePath, fn, opts): 메타 파일 쓰기 락 + fn 실행
- *   - withMetaLockSync(filePath, fn, opts): 위의 동기 변형 (sync 호출 체인용 — manifest 갱신)
- *   - getActiveTasks(mainWtPath): SSoT 조회 (git branch --list 'feature/*_TASK-*' ...)
- *   - getNextTaskNumber(mainWtPath): (진행중 ∪ 전 ref 머지 히스토리) 최대 + 1 (부모 무관 전역 채번)
- *   - forkTask(mainWtPath, {type,dev,src,slug}): init 락 안에서 부모(현재 브랜치) 캡처+채번+워크트리·브랜치 생성 원자 실행
- *   - currentBranch(mainWtPath): 메인 워크트리 현재 브랜치 = 부모 브랜치(detached면 'HEAD')
- *   - assertMainWorktreeOn(mainWtPath, branch): 메인 워크트리가 지정 브랜치 체크아웃 상태인지 검증
- *
- * 백로그 (0.1.2+):
- *   - getActiveVersion(mainWtPath): 활성 plan 식별자 — manifest.activePlan 우선, 구형 AGENT-GUIDE.md 폴백 (0.7.0+)
- *   - setActivePlan(mainWtPath, plan): manifest.activePlan 갱신 (plan 폴더 실재 검증 포함 — plan-switch)
- *   - getBacklogPath(mainWtPath, activeVersion?): .project/tasks/<활성 plan>/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 마크 (다회 진행 시 콤마 추가)
- */
-
+// taskery 1.0 명령이 함께 쓰는 도구 — git·경로·매니페스트·.state·잠금·태스크 문서·GIT_RULE 표·코드 지문
 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';
-
-// === 멀티 플랫폼 (0.2.0+) ===
-// 공통 소스 + 플랫폼별 조립 설치: 공통 자산(shared/)은 단일 소스로 보관하고
-// 설치 시 고른 플랫폼의 실제 경로로 매핑 복사한다. 플랫폼 고유 자산은 그대로 복사.
-const PLATFORMS = ['claude', 'codex'];
-const DEFAULT_PLATFORMS = ['claude']; // 기존(0.1.x) 설치 마이그레이션 기본값
-
-// shared/ 공통 자산의 플랫폼별 설치 경로 매핑.
-// shared 하위 첫 세그먼트(skills|hooks) → 각 플랫폼의 실제 설치 루트.
-// 스킬·git-guard 본문은 양 플랫폼 동일(검증 완료) — 단일 소스로 보관, 설치 때 갈라 깐다.
-const SHARED_DEST = {
-  claude: { skills: '.claude/skills', hooks: '.claude/hooks' },
-  codex: { skills: '.agents/skills', hooks: '.codex/hooks' },
-};
+const { execFileSync, spawn } = require('child_process');
 
-// template 상대경로 → 소속 ('agnostic' | 'shared' | 'claude' | 'codex')
-function platformOf(relPath) {
-  if (relPath.startsWith('shared/')) return 'shared'; // 공통 — 설치 시 플랫폼별 매핑
-  if (relPath === 'CLAUDE.md' || relPath.startsWith('.claude/')) return 'claude';
-  if (relPath.startsWith('.codex/')) return 'codex';
-  // AGENTS.md는 0.7.0부터 agnostic — 진입 문서 본문의 단일 소스이고
-  // CLAUDE.md는 이를 `@AGENTS.md`로 임포트만 한다(Claude Code는 AGENTS.md를 자동 로드하지 않음).
-  return 'agnostic'; // AGENTS.md, .project/, .gitignore 등 — 항상 설치
-}
-
-// shared/ 상대경로를 특정 플랫폼의 설치 경로로 변환.
-// 예: 'shared/skills/task-init/SKILL.md' + 'codex' → '.agents/skills/task-init/SKILL.md'
-function mapSharedDest(relPath, platform) {
-  const rest = relPath.slice('shared/'.length); // 'skills/task-init/SKILL.md'
-  const sep = rest.indexOf('/');
-  const top = sep === -1 ? rest : rest.slice(0, sep); // 'skills'
-  const tail = sep === -1 ? '' : rest.slice(sep); // '/task-init/SKILL.md'
-  const root = SHARED_DEST[platform] && SHARED_DEST[platform][top];
-  if (!root) {
-    throw new Error(`shared 자산 매핑 미정의: ${relPath} (platform=${platform})`);
-  }
-  return root + tail;
-}
-
-// template 파일맵을 설치 계획으로 전개 — [{ templateRel, installRel, hash }].
-//   - agnostic: 그대로 (includeAgnostic=false면 제외 — add 용)
-//   - shared: 선택 플랫폼마다 매핑 경로로 1건씩 전개 (1:N)
-//   - 플랫폼 고유: 선택 플랫폼이면 그대로
-function resolveInstallPlan(templateFiles, platforms, { includeAgnostic = true } = {}) {
-  const plan = [];
-  for (const [rel, hash] of Object.entries(templateFiles)) {
-    const p = platformOf(rel);
-    if (p === 'agnostic') {
-      if (includeAgnostic) plan.push({ templateRel: rel, installRel: rel, hash });
-    } else if (p === 'shared') {
-      for (const platform of platforms) {
-        plan.push({ templateRel: rel, installRel: mapSharedDest(rel, platform), hash });
-      }
-    } else if (platforms.includes(p)) {
-      plan.push({ templateRel: rel, installRel: rel, hash });
-    }
-  }
-  return plan;
+const MANIFEST_NAME = path.join('.taskery', 'manifest.json');
+// taskery가 설치하고 쓰는 파일 — 모두 git 밖(.git/info/exclude 이름 규칙, §3-4)
+const EXCLUDE_NAMES = ['.taskery', '.claude', '.codex', '.mcp.json', 'AGENTS.md', 'CLAUDE.md'];
+// 워크트리에 심는 방식 — 지침 파일은 복사, 나머지는 본진을 가리키는 링크(§3-4)
+const PLANT_COPY = ['AGENTS.md', 'CLAUDE.md'];
+const PLANT_LINK = ['.taskery', '.claude', '.codex', '.mcp.json'];
+
+const TYPES = ['feature', 'bug', 'improve', 'refactor', 'docs', 'chore'];
+const SIZES = ['small', 'medium', 'large'];
+const SWITCHES = ['plan', 'dev', 'test'];
+const DEFAULT_RANGE = '한 단계';
+// 브랜치 유형 → 커밋 태그 (GIT_RULE.md "커밋 태그" 표와 같다)
+const TAG_OF = { feature: 'feat', bug: 'fix', improve: 'improve', refactor: 'refactor', docs: 'docs', chore: 'docs' };
+const CODE_TEST_NOTICE_MS = 3 * 60 * 1000;
+
+// 명령이 멈출 때 쓰는 오류 — 메시지가 곧 "왜 멈췄고 다음에 무엇을 하라"이다
+class TaskeryError extends Error {}
+function fail(message) {
+  throw new TaskeryError(message);
 }
 
-// .gitignore 등록 패턴 (플랫폼별)
-const GITIGNORE_PATTERNS = {
-  agnostic: ['.project/', '.taskery-manifest.json', 'AGENTS.md'],
-  claude: ['.claude/', 'CLAUDE.md'],
-  codex: ['.codex/', '.agents/'],
-};
+// ─── git ─────────────────────────────────────────────
 
-// 선택 플랫폼 + agnostic의 gitignore 패턴 합성 (중복 제거)
-function gitignorePatternsFor(platforms) {
-  const out = [...GITIGNORE_PATTERNS.agnostic];
-  for (const p of platforms) {
-    for (const pat of GITIGNORE_PATTERNS[p] || []) {
-      if (!out.includes(pat)) out.push(pat);
-    }
+function git(cwd, args, opts = {}) {
+  try {
+    return execFileSync('git', ['-C', cwd, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      maxBuffer: 64 * 1024 * 1024,
+    }).replace(/\s+$/, '');
+  } catch (e) {
+    if (opts.allowFail) return null;
+    const msg = ((e.stderr || '') + (e.stdout || '')).toString().trim();
+    throw new TaskeryError(`git ${args.join(' ')} 실패: ${msg || e.message}`);
   }
-  return out;
 }
 
-function findTemplateDir() {
-  // 패키지 루트는 이 lib.js 파일의 부모(bin/)의 부모
-  const pkgRoot = path.resolve(__dirname, '..');
-  const tmpl = path.join(pkgRoot, 'template');
-  if (!fs.existsSync(tmpl)) {
-    throw new Error(`template/ not found at ${tmpl}. taskery 패키지 설치 손상 가능성.`);
-  }
-  return tmpl;
+function gitOk(cwd, args) {
+  return git(cwd, args, { allowFail: true }) !== null;
 }
 
-function sha256(filePath) {
-  const buf = fs.readFileSync(filePath);
-  return 'sha256:' + crypto.createHash('sha256').update(buf).digest('hex');
+// 본진 = 공통 .git의 부모 폴더. 워크트리 안에서 불러도 본진을 돌려준다
+function findMain(cwd = process.cwd()) {
+  const common = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir'], { allowFail: true });
+  if (!common) fail(`git 리포 안이 아니다 (${cwd}). taskery를 설치한 리포에서 부른다.`);
+  return path.dirname(common);
 }
 
-// 파일이 아니라 *써 넣을 내용*의 해시. 조립해서 설치하는 자산(AGENTS.md)은 템플릿 원본과
-// 내용이 다르므로, manifest에는 반드시 조립 결과물의 해시를 기록해야 한다.
-function sha256Text(text) {
-  return 'sha256:' + crypto.createHash('sha256').update(Buffer.from(text, 'utf8')).digest('hex');
+function currentBranch(dir) {
+  const b = git(dir, ['symbolic-ref', '--short', '-q', 'HEAD'], { allowFail: true });
+  return b || null; // detached HEAD면 null
 }
 
-function walkTemplate(templateDir) {
-  // template/ 안 모든 파일 상대경로 + 해시 맵 리턴
-  // 결과: { 'CLAUDE.md': 'sha256:...', '.claude/skills/task-init/SKILL.md': 'sha256:...', ... }
-  const result = {};
-  function walk(dir, relBase) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) {
-        walk(full, rel);
-      } else if (entry.isFile()) {
-        result[rel] = sha256(full);
-      }
-    }
+// 커밋 안 된 변경(추적 안 되는 파일 포함, exclude된 taskery 파일 제외) 경로 목록
+function changedFiles(dir) {
+  const out = git(dir, ['status', '--porcelain', '-z', '-uall']);
+  if (!out) return [];
+  const parts = out.split('\0').filter(Boolean);
+  const files = [];
+  for (let i = 0; i < parts.length; i++) {
+    const code = parts[i].slice(0, 2);
+    files.push(parts[i].slice(3));
+    if (code[0] === 'R' || code[0] === 'C') files.push(parts[++i]); // 원래 경로
   }
-  walk(templateDir, '');
-  return result;
+  return files;
 }
 
-function mkdirp(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
+// 추적 중인 파일의 커밋 안 된 변경 경로 목록(추적 안 되는 파일 제외)
+function trackedChanges(dir) {
+  const out = git(dir, ['status', '--porcelain', '-uno']);
+  return out ? out.split('\n').map((l) => l.slice(3)) : [];
 }
 
-function copyFile(src, dst) {
-  mkdirp(path.dirname(dst));
-  fs.copyFileSync(src, dst);
-  // 실행 권한 보존 (hooks .sh 파일)
-  if (src.endsWith('.sh')) {
-    fs.chmodSync(dst, 0o755);
-  }
+function isAncestor(dir, a, b) {
+  return gitOk(dir, ['merge-base', '--is-ancestor', a, b]);
 }
 
-function writeManifest(manifest, dst) {
-  fs.writeFileSync(dst, JSON.stringify(manifest, null, 2) + '\n');
+function branchExists(dir, branch) {
+  return gitOk(dir, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]);
 }
 
-function readManifest(filePath) {
-  if (!fs.existsSync(filePath)) return null;
+// 코드 지문 = 작업 트리 전체(추적 안 되는 파일 포함, 무시 파일 제외)의 트리 해시. 커밋하지 않는다.
+// 임시 인덱스는 본진 .taskery/.state/ 아래에 둔다 — Codex 샌드박스에서도 쓰기가 허용된 곳이다(--add-dir <본진>/.taskery)
+function fingerprint(dir) {
+  const index = git(dir, ['rev-parse', '--path-format=absolute', '--git-path', 'index']);
+  const tmpDir = stateDir(findMain(dir));
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const tmp = path.join(tmpDir, `taskery-index-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (e) {
-    throw new Error(`${filePath} 파싱 실패: ${e.message}`);
+    if (fs.existsSync(index)) fs.copyFileSync(index, tmp);
+    const env = { GIT_INDEX_FILE: tmp };
+    git(dir, ['add', '-A'], { env });
+    return git(dir, ['write-tree'], { env });
+  } finally {
+    fs.rmSync(tmp, { force: true });
   }
 }
 
-function isLocalOverride(relPath) {
-  // *.local.md suffix 사용자 오버라이드 — npx 미터치 명시
-  return relPath.endsWith(LOCAL_SUFFIX);
+// extra = 매니페스트에 등록된 빌드 결과 폴더 — 코드로 커밋되지 않게 같은 이름 규칙으로 넣는다(§7)
+function ensureExclude(main, extra = []) {
+  const common = git(main, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const file = path.join(common, 'info', 'exclude');
+  const cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const have = new Set(cur.split('\n').map((l) => l.trim()));
+  const names = [...EXCLUDE_NAMES, ...(Array.isArray(extra) ? extra : [])].map((n) => String(n).replace(/^\/+|\/+$/g, ''));
+  const missing = [...new Set(names.map((n) => `/${n}`))].filter((r) => !have.has(r));
+  if (missing.length === 0) return [];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const sep = cur && !cur.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(file, `${sep}# taskery\n${missing.join('\n')}\n`);
+  return missing;
 }
 
-function getPackageVersion() {
-  const pkgPath = path.resolve(__dirname, '..', 'package.json');
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-  return pkg.version;
+// Orca 탭 안인가 — Orca가 탭에 넣는 환경 변수로 판단한다
+function inOrca() {
+  return !!process.env.ORCA_TERMINAL_HANDLE;
 }
 
-// === 멀티세션 (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 runShell(cmd, cwd) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn('sh', ['-c', `exec 2>&1\n${cmd}`], { cwd, env: process.env });
+    let out = '';
+    child.stdout.on('data', (d) => {
+      out += d.toString();
+      if (out.length > 4 * 1024 * 1024) out = out.slice(-2 * 1024 * 1024);
+    });
+    child.on('close', (code) => resolve({ code, out, ms: Date.now() - started }));
+    child.on('error', (e) => resolve({ code: 127, out: String(e.message), ms: Date.now() - started }));
+  });
+}
 
-function generateProjectId() {
-  return crypto.randomBytes(4).toString('hex');
+function tail(text, lines) {
+  const arr = text.replace(/\s+$/, '').split('\n');
+  return arr.slice(-lines).join('\n');
 }
 
-function gitCapture(cwd, args, opts = {}) {
+// ─── 매니페스트 · 설치 확인 ───────────────────────────
+
+// 0.x 설치본의 매니페스트 이름(리포 맨 위). 1.0은 이 이름을 쓰지 않으니, 있으면 0.x 설치본이다
+const OLD_MANIFEST_NAME = '.taskery-manifest.json';
+
+// 리포 맨 위에 0.x 매니페스트가 있으면 멈춘다 — update·init 공통(§3-1). caller로 부르는 명령에 맞는 문구를 낸다
+function checkLegacyInstall(main, caller) {
+  const old = path.join(main, OLD_MANIFEST_NAME);
+  if (!fs.existsSync(old)) return;
+  let version = '0.x';
   try {
-    return execFileSync('git', ['-C', cwd, ...args], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', opts.captureStderr ? 'pipe' : 'ignore'],
-    }).trimEnd();
+    version = JSON.parse(fs.readFileSync(old, 'utf8')).version || '0.x';
   } catch (e) {
-    if (opts.allowFail) return null;
-    throw e;
+    // 깨진 파일이어도 0.x 설치본으로 취급한다
+  }
+  const oldFiles = '옛 taskery 파일(AGENTS.md·CLAUDE.md·.claude/·.codex/·.agents/·.project/·.mcp.json·.taskery-manifest.json)';
+  const moveOldDocs = "필요한 옛 문서(백로그·제품 문서)는 옮겨 둔 곳에서 새 .taskery/로 가져온다.";
+  if (caller === 'init') {
+    fail(
+      `init: 이 리포는 taskery ${version}로 설치돼 있어 그 위에 1.0을 설치할 수 없다(1.0은 0.x와 호환되지 않는다). ${oldFiles}을 리포 밖으로 옮긴 뒤 다시 init한다. ${moveOldDocs}`,
+    );
   }
+  fail(
+    `update: 이 리포는 taskery ${version}로 설치돼 있어 update로 옮길 수 없다(1.0은 0.x와 호환되지 않는다). ${oldFiles}을 리포 밖으로 옮긴 뒤 'npx @angar2/taskery init'으로 새로 설치한다. ${moveOldDocs}`,
+  );
 }
 
-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 readManifest(main) {
+  const file = path.join(main, MANIFEST_NAME);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
-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 writeManifest(main, m) {
+  const file = path.join(main, MANIFEST_NAME);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(m, null, 2) + '\n');
 }
 
-function getWorktreesRoot(projectId) {
-  return path.join(TASKERY_HOME, 'worktrees', projectId);
+function requireInstalled(main) {
+  const m = readManifest(main);
+  if (!m) fail(`taskery가 설치돼 있지 않다 (${main}). 리포 루트에서 'npx @angar2/taskery init'을 먼저 부른다.`);
+  return m;
 }
 
-function getWorktreePath(projectId, { taskNum, src, slug }) {
-  // src = 'BL-NNN' | 'ST-N'(로드맵 Stage) | 'DR' (구형 'RM-NNN' 호환)
-  const nnn = String(taskNum).padStart(3, '0');
-  return path.join(getWorktreesRoot(projectId), `TASK-${nnn}_${src}_${slug}`);
+function getPackageVersion() {
+  return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')).version;
 }
 
-function getMergeLockPath(projectId) {
-  return path.join(TASKERY_HOME, `${projectId}.merge.lock`);
-}
+// ─── .state · 잠금 ──────────────────────────────────
 
-function getInitLockPath(projectId) {
-  return path.join(TASKERY_HOME, `${projectId}.init.lock`);
+function stateDir(main) {
+  return path.join(main, '.taskery', '.state');
 }
 
-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();
-  }
+function pad(num) {
+  return String(num).padStart(3, '0');
 }
 
-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 taskLabel(num) {
+  return `TASK-${pad(num)}`;
 }
 
-function withMetaLockSync(filePath, fn, opts = {}) {
-  // withMetaLock의 동기 변형. manifest 갱신 경로(initPlan → plan.js main)가 전부 sync라
-  // async 락을 쓰면 호출 사슬 전체를 async로 바꿔야 해 동기 락을 별도로 둔다.
-  const lockfile = require('proper-lockfile');
-  if (!fs.existsSync(filePath)) {
-    mkdirp(path.dirname(filePath));
-    fs.writeFileSync(filePath, '');
-  }
-  // sync API는 retries를 지원하지 않는다(proper-lockfile 제약). 경합 시 즉시 던지는데,
-  // manifest 쓰기는 사용자가 직접 부르는 명령들뿐이라 동시 실행이 실질적으로 없다.
-  const release = lockfile.lockSync(filePath, {
-    stale: opts.stale ?? DEFAULT_LOCK_TIMEOUT_MS,
-    realpath: false,
-  });
-  try {
-    return fn();
-  } finally {
-    release();
-  }
+function parseTaskNum(token) {
+  const m = String(token || '').match(/^(?:TASK-)?(\d+)$/i);
+  if (!m) fail(`태스크 번호를 읽지 못했다: '${token}'. 'TASK-012'나 '12'처럼 넘긴다.`);
+  return parseInt(m[1], 10);
 }
 
-function currentBranch(mainWtPath) {
-  // 메인 워크트리의 현재 브랜치 = 태스크의 부모 브랜치(0.6.0). detached HEAD면 'HEAD' 반환.
-  return gitCapture(mainWtPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+function writeJsonAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  fs.renameSync(tmp, file);
 }
 
-function assertMainWorktreeOn(mainWtPath, branch) {
-  const current = currentBranch(mainWtPath);
-  if (current !== branch) {
-    throw new Error(`메인 워크트리가 ${branch} 아님 (현재: ${current}). 부모 브랜치로 체크아웃 필요.`);
-  }
+function statePath(main, num) {
+  return path.join(stateDir(main), 'tasks', `${pad(num)}.json`);
 }
 
-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 <부모>` 미사용:
-  // 워크트리 분기 직후 브랜치는 부모와 동일 commit이라 `--no-merged`가 *완전 머지 상태*로
-  // 처리 → 빈 결과 → 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 readState(main, num) {
+  const file = statePath(main, num);
+  if (!fs.existsSync(file)) fail(`${taskLabel(num)}의 기록이 없다. 'status'로 열린 태스크 번호를 확인한다.`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
-function getNextTaskNumber(mainWtPath) {
-  // 1. 진행중 (SSoT)
-  const activeNums = getActiveTasks(mainWtPath).map((t) => t.taskNum);
-  // 2. 머지 히스토리 (GIT_RULE 풍부 메시지) — 모든 ref(`--all`) 스캔.
-  //    부모 브랜치가 dev로 고정되지 않으므로(0.6.0) 닫힌 태스크는 각자의 부모에 병합돼 있다.
-  //    특정 부모(과거 'dev') 하나만 grep하면 다른 부모로 닫힌 번호를 놓쳐 채번 충돌 → `--all`로
-  //    전 ref의 TASK-NNN 최대를 취해 번호를 리포 전역으로 유지.
-  //    --extended-regexp(ERE)에서 `+`는 수량자 — `\+`는 *리터럴 +* 라 "TASK-001"을 못 잡는다.
-  const log = gitCapture(mainWtPath, [
-    'log',
-    '--all',
-    '--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;
-}
-
-async function forkTask(mainWtPath, { type, dev, src, slug }) {
-  // task 분기 — [채번 → 워크트리·브랜치 생성]을 init 락(withMetaLock)으로 원자화.
-  // 병렬 task-init이 같은 번호를 읽고 각자 브랜치를 만들던 레이스(TOCTOU)를 차단: 락 안에서
-  // getNextTaskNumber 직후 worktree add까지 끝내므로 다음 호출은 늘어난 번호를 본다.
-  const projectId = getProjectId(mainWtPath);
-  return withMetaLock(getInitLockPath(projectId), () => {
-    // 부모 = 메인 워크트리의 현재 브랜치(0.6.0). dev 하드코딩 제거 — 서 있는 브랜치가 곧 부모.
-    const parent = currentBranch(mainWtPath);
-    if (parent === 'HEAD') {
-      throw new Error('메인 워크트리가 detached HEAD — 부모로 삼을 브랜치에 체크아웃 필요.');
-    }
-    // SSoT 안전망 — 같은 항목 출처(BL-NNN/구형 RM-NNN)가 이미 진행중이면 거부.
-    // DR(별도 ID 없음)·ST-N(Stage 하나에서 복수 task가 정상)은 검사 제외.
-    if (/^(BL|RM)-/.test(src)) {
-      const dup = getActiveTasks(mainWtPath).find((t) => t.src === src);
-      if (dup) {
-        throw new Error(`${src} 이미 진행중 (${dup.branch}) — 다른 세션이 같은 항목 진행`);
-      }
-    }
-    const taskNum = getNextTaskNumber(mainWtPath); // 락 안 → TOCTOU 차단
-    const nnn = String(taskNum).padStart(3, '0');
-    const branch = `${type}/${dev}_TASK-${nnn}_${src}_${slug}`;
-    const wtPath = getWorktreePath(projectId, { taskNum, src, slug });
-    mkdirp(getWorktreesRoot(projectId));
-    // 부모 브랜치를 base로 워크트리·브랜치 생성. 동일 브랜치명은 git이 거부(같은 항목 동시 분기
-    // 차단). 실패 시 throw → fork.js가 사용자 보고.
-    execFileSync('git', ['-C', mainWtPath, 'worktree', 'add', wtPath, '-b', branch, parent], {
-      stdio: 'pipe',
-    });
-    return { taskNum, nnn, branch, wtPath, projectId, parent };
-  });
+function writeState(main, st) {
+  writeJsonAtomic(statePath(main, st.num), st);
 }
 
-function computeNextPlanNumber(mainWtPath) {
-  // .project/plans/ 하위 'NNN_<slug>' 디렉토리 스캔 → NNN max+1, 3자리 zero-pad 문자열 반환.
-  // plan = 기능 그룹 단위, 폴더명 앞 3자리 채번(TASK-NNN과 결 맞춤). slug은 호출측(plan-init)이 결합.
-  // legacy 가드: 'NNN_' 패턴이 아닌 폴더(구버전 vX.X 등)는 legacyDirs로 수집 → plan-init이
-  //   새 plan 생성 전 경고·수동 이전 안내에 사용(채번 공존 시 활성 plan 갈림 = 원 문제 재발 차단).
-  const plansDir = path.join(mainWtPath, '.project', 'plans');
-  if (!fs.existsSync(plansDir)) {
-    return { next: '001', legacyDirs: [] };
-  }
-  const nums = [];
-  const legacyDirs = [];
-  for (const ent of fs.readdirSync(plansDir, { withFileTypes: true })) {
-    if (!ent.isDirectory()) continue;
-    const m = ent.name.match(/^(\d{3})_/);
-    if (m) nums.push(parseInt(m[1], 10));
-    else legacyDirs.push(ent.name);
-  }
-  const next = nums.length === 0 ? 1 : Math.max(...nums) + 1;
-  return { next: String(next).padStart(3, '0'), legacyDirs };
-}
-
-// ─── 백로그 (0.1.2+) ────────────────────────────────────────────────
-
-const BACKLOG_PLACEHOLDER =
-  '(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)';
-
-// 구형(0.7.0 미만) 활성 plan 저장소 — .project/AGENT-GUIDE.md '## 활성 plan 버전' 섹션.
-// 0.7.0에서 SSoT가 manifest.activePlan으로 이관됐으나, update 전 리포를 무중단으로 굴리기 위해
-// 읽기 폴백으로만 남긴다. 쓰기는 하지 않는다(_setActivePlan은 manifest만 갱신).
-// 헤딩 줄 끝 부가 텍스트(HTML 주석 등) 허용 — project-init 골격이 헤딩에 주석을 달므로 접두 일치로 판정.
-// 완전 일치를 요구하면 자기 골격을 자기가 못 읽는 자기모순 (recordion FRICTION 2026-08-06, scaffoldError 6회).
-function _readLegacyActivePlan(mainWtPath) {
-  const guidePath = path.join(mainWtPath, '.project', 'AGENT-GUIDE.md');
-  if (!fs.existsSync(guidePath)) return null;
-  const sec = fs.readFileSync(guidePath, 'utf8').match(/^##\s*활성 plan 버전[^\n]*\n+([^\n]+)/m);
-  if (!sec) return null;
-  // 첫 토큰 = plan 폴더 이름(' — 설명' 앞부분). '<예: ...>' 자리표시자는 미설정으로 간주.
-  const firstLine = sec[1].trim();
-  if (!firstLine || firstLine.startsWith('<')) return null;
-  return firstLine.split(/\s+/)[0];
-}
-
-function getActiveVersion(mainWtPath) {
-  // 활성 plan 식별자 = manifest.activePlan (0.7.0+ SSoT). plan = 기능 그룹 단위라
-  // 식별자는 NNN_slug 폴더명(구형은 vX.X 버전명도 가능).
-  const manifest = readManifest(path.join(mainWtPath, MANIFEST_NAME));
-  if (manifest && manifest.activePlan) return manifest.activePlan;
-
-  // 구형 폴백 — update 전 리포. 읽기만 하고 승격은 update가 1회 수행한다.
-  const legacy = _readLegacyActivePlan(mainWtPath);
-  if (legacy) return legacy;
-
-  if (!manifest) {
-    throw new Error(`${MANIFEST_NAME} 부재. 'npx @angar2/taskery init' 먼저 실행.`);
-  }
-  throw new Error(
-    `활성 plan 미설정 (manifest.activePlan 없음) — /plan-init으로 plan을 생성하거나 ` +
-      `'npx @angar2/taskery plan-switch <NNN_slug>'로 지정 필요.`,
-  );
+function listStates(main) {
+  const dir = path.join(stateDir(main), 'tasks');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => /^\d+\.json$/.test(f))
+    .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')))
+    .sort((a, b) => a.num - b.num);
 }
 
-function setActivePlan(mainWtPath, plan) {
-  // plan-switch — 대상 plan 폴더 실재 검증 후 manifest.activePlan 갱신.
-  const planDir = path.join(mainWtPath, '.project', 'plans', plan);
-  if (!fs.existsSync(planDir)) {
-    throw new Error(`plan 폴더 부재: ${planDir} — 존재하는 plan만 활성으로 지정 가능.`);
+// 잠금 — .taskery/.state/<name>.lock. wait=true면 풀릴 때까지 기다린다
+async function withLock(main, name, fn) {
+  const lockfile = require('proper-lockfile');
+  const file = path.join(stateDir(main), `${name}.lock`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!fs.existsSync(file)) fs.writeFileSync(file, '');
+  const release = await lockfile.lock(file, {
+    stale: 60000,
+    realpath: false,
+    retries: { retries: 100000, factor: 1, minTimeout: 300, maxTimeout: 1000 },
+  });
+  try {
+    return await fn();
+  } finally {
+    await release();
   }
-  _setActivePlan(mainWtPath, plan);
-  return { plan, planDir };
 }
 
-function getBacklogPath(mainWtPath, activeVersion) {
-  const v = activeVersion ?? getActiveVersion(mainWtPath);
-  return path.join(mainWtPath, '.project', 'tasks', v, 'BACKLOG.md');
+// 단계 판정에 쓰는 정의
+function sw(st, name) {
+  return st.switch.includes(name);
 }
 
-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;
+// 병합이 필요 없는 태스크 — 개발 꺼짐·브랜치 생략·코드 변경 없음(§5-3)
+function needsNoMerge(st) {
+  return !sw(st, 'dev') || st.noBranch || !!(st.commit && st.commit.noCodeChange);
 }
 
-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}`;
+// 끝난 태스크 = 마무리 기록이 있는 태스크(병합 기록, 병합이 필요 없으면 commit-task 완료 기록, §5-3)
+function hasFinishRecord(st) {
+  if (st.merge && st.merge.commit) return true;
+  return needsNoMerge(st) && !!st.commit;
 }
 
-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 workDir(main, st) {
+  return st.worktree || main;
 }
 
-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'));
-  });
-}
+// ─── GIT_RULE.md 맨 위 표 ─────────────────────────────
 
-// ─── task 헤더 / 상태 전이 (코드화) ─────────────────────────────────
-// 헤더 파싱(6컬럼 · 구 5컬럼 폴백) · task 문서 위치 판정 · 7상태 유효전이 검증을 코드로 단일화.
-// 계약: TASK_DOC_RULE §1.1(헤더) · §1.2(7상태) · §1.5(문서 위치).
-
-// 7×7 유효전이표 (TASK_DOC_RULE §1.2 + FAIL/UNCERTAIN 분기). from → 허용 to 목록.
-//   - 정상 진행: draft→planned→developing→developed→testing→tested→closed
-//   - 되돌림: testing→developing (task-test FAIL "코드 결함" 사용자 "고쳐")
-//   - closed는 종료 상태(빈 목록) — closed-immutable hook이 이후 본 파일 잠금.
-const TRANSITIONS = {
-  draft: ['planned'],
-  planned: ['developing'],
-  developing: ['developed'],
-  developed: ['testing'],
-  testing: ['tested', 'developing'],
-  tested: ['closed'],
-  closed: [],
+const GIT_RULE_DEFAULTS = {
+  integration: 'dev',
+  branch: '{type}/{dev}_TASK-{num}_{slug}',
+  commit: '{tag}: [TASK-{num}] {summary}',
+  merge: 'no-ff',
+};
+const GIT_RULE_KEYS = {
+  '통합 브랜치': 'integration',
+  '브랜치 이름': 'branch',
+  '커밋 메시지': 'commit',
+  '병합 방식': 'merge',
 };
 
-function _locateHeaderRow(content) {
-  // 헤더 표(라벨행 → 구분선 → 데이터행)에서 데이터행을 찾아 split 셀과 줄 인덱스 반환.
-  // 데이터행 셀: `| a | b | c | d | e |` → split('|') = ['', ' a ', ..., ' e ', '']. null이면 표 부재.
-  const lines = content.split('\n');
-  let labelIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const l = lines[i];
-    if (l.trimStart().startsWith('|') && l.includes('생성일') && l.includes('상태')) {
-      labelIdx = i;
-      break;
-    }
+function parseGitRuleTable(text) {
+  const rule = {};
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*$/);
+    if (!m) continue;
+    const key = GIT_RULE_KEYS[m[1]];
+    if (key && !rule[key]) rule[key] = m[2].replace(/`/g, '').trim();
   }
-  if (labelIdx === -1) return null;
-  let dataIdx = -1;
-  for (let j = labelIdx + 1; j < lines.length; j++) {
-    const t = lines[j].trim();
-    if (t === '') continue;
-    if (/^[|\s:-]+$/.test(t)) continue; // 구분선 (|---|---|)
-    if (lines[j].trimStart().startsWith('|')) {
-      dataIdx = j;
-      break;
-    }
-    break; // 표 끝
-  }
-  if (dataIdx === -1) return null;
-  return { lines, dataIdx, cells: lines[dataIdx].split('|') };
-}
-
-function parseTaskHeader(taskMdPath) {
-  // 헤더를 구조화 → { created, plan, type, size, parent, status }. 표 부재/컬럼 부족 시 throw.
-  // 6컬럼(0.6.0+): 생성일·플랜·유형·규모·부모 브랜치·상태. 부모 브랜치는 상태 *앞* — 상태를
-  // 항상 마지막 셀로 유지해 setStatus의 `length-2` 로직이 구·신 양쪽에서 성립하게 함.
-  // 5컬럼(구): 부모 칸 부재 → parent='dev' 폴백(0.6.0 이전 문서 하위호환).
-  const content = fs.readFileSync(taskMdPath, 'utf8');
-  const loc = _locateHeaderRow(content);
-  if (!loc) throw new Error(`헤더 표 파싱 실패 (TASK_DOC_RULE §1.1 형식 아님): ${taskMdPath}`);
-  const inner = loc.cells.slice(1, -1).map((c) => c.trim());
-  if (inner.length < 5) {
-    throw new Error(`헤더 표 컬럼 부족(${inner.length}/5): ${taskMdPath}`);
-  }
-  if (inner.length >= 6) {
-    const [created, plan, type, size, parent, status] = inner;
-    return { created, plan, type, size, parent, status };
-  }
-  const [created, plan, type, size, status] = inner;
-  return { created, plan, type, size, parent: 'dev', status };
+  return rule;
 }
 
-function isProjectRegistered(mainWtPath) {
-  // .gitignore에 .project/ 등록 여부 — check-ignore exit 0 = 등록(퍼블릭 default, 문서는 메인WT 공유),
-  // exit 1 = 미등록(문서는 워크트리 안, 머지로 부모 반영). task-init Step7 분기와 동일 판정.
-  try {
-    execFileSync(
-      'git',
-      ['-C', mainWtPath, 'check-ignore', '-q', path.join(mainWtPath, '.project', 'dummy')],
-      { stdio: 'ignore' },
-    );
-    return true;
-  } catch (e) {
-    return false;
+function readGitRule(main) {
+  const file = path.join(main, '.taskery', 'rules', 'GIT_RULE.md');
+  const rule = fs.existsSync(file) ? parseGitRuleTable(fs.readFileSync(file, 'utf8')) : {};
+  const merged = { ...GIT_RULE_DEFAULTS, ...rule };
+  if (!['no-ff', 'ff-only'].includes(merged.merge)) {
+    fail(`GIT_RULE.md 표의 병합 방식 '${merged.merge}'을 읽지 못했다. 'no-ff'나 'ff-only'로 적는다.`);
   }
+  return merged;
 }
 
-function resolveTaskDocPath(mainWtPath, wtPath, { taskNum }) {
-  // task 문서 위치 단일 판정 — 등록 케이스로 base 결정 후 taskNum으로 탐색.
-  // 단일 파일(`<NNN>_<slug>.md`) / 폴더 승격(`TASK-<NNN>_<slug>/task.md`) 양쪽 + plan 폴더 무관(*) 글롭.
-  // 발견 못하면 null. 반환: { registered, plan, promoted, dir, file }.
-  const nnn = String(taskNum).padStart(3, '0');
-  const registered = isProjectRegistered(mainWtPath);
-  const base = registered ? mainWtPath : wtPath;
-  const tasksRoot = path.join(base, '.project', 'tasks');
-  if (!fs.existsSync(tasksRoot)) return null;
-  const fileRe = new RegExp(`^${nnn}_.+\\.md$`);
-  const dirRe = new RegExp(`^TASK-${nnn}_`);
-  for (const planEnt of fs.readdirSync(tasksRoot, { withFileTypes: true })) {
-    if (!planEnt.isDirectory()) continue;
-    const planDir = path.join(tasksRoot, planEnt.name);
-    for (const ent of fs.readdirSync(planDir, { withFileTypes: true })) {
-      if (ent.isFile() && fileRe.test(ent.name)) {
-        return {
-          registered,
-          plan: planEnt.name,
-          promoted: false,
-          dir: planDir,
-          file: path.join(planDir, ent.name),
-        };
-      }
-      if (ent.isDirectory() && dirRe.test(ent.name)) {
-        const f = path.join(planDir, ent.name, 'task.md');
-        if (fs.existsSync(f)) {
-          return {
-            registered,
-            plan: planEnt.name,
-            promoted: true,
-            dir: path.join(planDir, ent.name),
-            file: f,
-          };
-        }
-      }
-    }
-  }
-  return null;
+function fillTemplate(tpl, vars) {
+  return tpl.replace(/\{(\w+)\}/g, (all, k) => (k in vars ? vars[k] : all));
 }
 
-async function setStatus(taskMdPath, next) {
-  // 헤더 상태 컬럼을 next로 전이 — 현재 상태 읽고 7×7 표 검증 후 치환 (withMetaLock 직렬화).
-  //   - next가 7상태 아님 → throw. 현재==next → idempotent no-op (changed:false).
-  //   - 유효전이 아님 → throw (잘못된 전이 거부).
-  if (!Object.prototype.hasOwnProperty.call(TRANSITIONS, next)) {
-    throw new Error(`알 수 없는 상태: ${next} (유효: ${Object.keys(TRANSITIONS).join(', ')})`);
-  }
-  if (!fs.existsSync(taskMdPath)) throw new Error(`task 문서 없음: ${taskMdPath}`);
-  return await withMetaLock(taskMdPath, async () => {
-    const content = fs.readFileSync(taskMdPath, 'utf8');
-    const loc = _locateHeaderRow(content);
-    if (!loc) throw new Error(`헤더 표 파싱 실패: ${taskMdPath}`);
-    const trimmed = loc.cells.slice(1, -1).map((c) => c.trim());
-    const cur = trimmed[trimmed.length - 1]; // 상태 = 항상 마지막 셀 (6컬럼: 부모 브랜치가 그 앞)
-    if (cur === next) return { changed: false, from: cur, to: next, path: taskMdPath };
-    const allowed = TRANSITIONS[cur] || [];
-    if (!allowed.includes(next)) {
-      throw new Error(
-        `잘못된 전이: ${cur} → ${next} (허용: ${allowed.length ? allowed.join(', ') : '없음 — 종료 상태'})`,
-      );
-    }
-    const statusCellIdx = loc.cells.length - 2; // 마지막 빈 셀 직전 = 상태
-    loc.cells[statusCellIdx] = loc.cells[statusCellIdx].replace(cur, next);
-    loc.lines[loc.dataIdx] = loc.cells.join('|');
-    fs.writeFileSync(taskMdPath, loc.lines.join('\n'));
-    return { changed: true, from: cur, to: next, path: taskMdPath };
-  });
-}
+// ─── 태스크 문서 ─────────────────────────────────────
 
-// ─── task 문서 골격 생성 (코드화, C1) ───────────────────────────────
-// fork 직후 §1.3 빈 골격을 코드가 자동 생성 — 생성일=오늘 / status=draft 자동, 파일명 규칙 코드 보장.
+function docAbs(main, st) {
+  return path.join(main, st.doc);
+}
 
-// 생성일=오늘(로컬 타임존 YYYY-MM-DD). toISOString()은 UTC라 KST 자정~09시 사이 전날로 박힘 → 로컬 산출.
-function _todayLocal() {
-  const d = new Date();
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, '0');
-  const day = String(d.getDate()).padStart(2, '0');
-  return `${y}-${m}-${day}`;
+// 사람·AI에게 보여 주는 문서 경로 — 워크트리가 있으면 그 안의 링크 너머 경로(같은 파일).
+// 워크트리에 들어간 세션은 본진 경로 편집이 막히기 때문이다. 읽기·쓰기는 docAbs(본진) 그대로
+function docShown(main, st) {
+  if (st.worktree && fs.existsSync(st.worktree)) return path.join(st.worktree, st.doc);
+  return docAbs(main, st);
 }
 
-// 브랜치 타입 → 문서 유형(§1.1). improve↔improvement만 다름.
-const DOC_TYPE_OF = {
-  feature: 'feature',
-  bug: 'bug',
-  improve: 'improvement',
-  refactor: 'refactor',
-  docs: 'docs',
-  chore: 'chore',
-};
+function readDoc(main, st) {
+  const file = docAbs(main, st);
+  if (!fs.existsSync(file)) fail(`태스크 문서가 없다: ${docShown(main, st)}`);
+  return fs.readFileSync(file, 'utf8');
+}
 
-function _buildTaskDocPath(base, plan, { taskNum, slug, promoted }) {
-  const nnn = String(taskNum).padStart(3, '0');
-  const planDir = path.join(base, '.project', 'tasks', plan);
-  if (promoted) {
-    const dir = path.join(planDir, `TASK-${nnn}_${slug}`);
-    return { dir, file: path.join(dir, 'task.md') };
+// 줄마다 코드 블록 안인지 — ``` 또는 ~~~로 시작하는 줄이 블록을 열고 닫는다. 닫히지 않은 블록은 문서 끝에서 닫힌 것으로 본다
+function fenceMask(lines) {
+  const mask = [];
+  let open = false;
+  for (const l of lines) {
+    if (/^\s*(```|~~~)/.test(l)) {
+      mask.push(true);
+      open = !open;
+      continue;
+    }
+    mask.push(open);
   }
-  return { dir: planDir, file: path.join(planDir, `${nnn}_${slug}.md`) };
+  return mask;
 }
 
-function _renderTaskSkeleton({ taskNum, title, created, plan, docType, size, parent }) {
-  const nnn = String(taskNum).padStart(3, '0');
-  return [
-    `# TASK-${nnn} — ${title}`,
-    '',
-    '| 생성일 | 플랜 | 유형 | 규모 | 부모 브랜치 | 상태 |',
-    '|--------|------|------|------|-------------|------|',
-    `| ${created} | ${plan} | ${docType} | ${size} | ${parent} | draft |`,
-    '',
-    '## Requirements',
-    '',
-    '(사용자 요구 + 메인 증폭 — `/task-plan`에서 채움)',
-    '',
-    '## Scope',
-    '',
-    '(영향 범위 — `/task-plan`에서 채움)',
-    '',
-    '## Dev Plan',
-    '',
-    '(Phase 1, 2, ... — `/task-plan`에서 채움)',
-    '',
-    '## Test Plan',
-    '',
-    '(테스트 방법 + 검증 명령 — `/task-plan`에서 채움)',
-    '',
-    '## Result',
-    '',
-    '(진행 + 테스트 결과 — `/task-dev`, `/task-test`에서 채움)',
-    '',
-  ].join('\n');
-}
-
-function scaffoldTaskDoc(mainWtPath, wtPath, meta) {
-  // meta: { taskNum, slug, title, type(브랜치 타입), size, parent, plan?, promoted?, created? }
-  // 위치: 등록(.gitignore) 케이스 → 메인WT, 미등록 → 워크트리. plan 미지정 시 활성 plan(manifest.activePlan)에서 검출.
-  // parent 미지정 시 현재 브랜치 캡처(단독 호출 안전망 — 통상 fork가 넘김).
-  // taskNum이 고유(fork init 락 채번)라 동일 문서 동시 쓰기 경합 없음 → 락 불요.
-  const registered = isProjectRegistered(mainWtPath);
-  const base = registered ? mainWtPath : wtPath;
-  const plan = meta.plan || getActiveVersion(mainWtPath);
-  const docType = DOC_TYPE_OF[meta.type] || meta.type;
-  const created = meta.created || _todayLocal();
-  const parent = meta.parent || currentBranch(mainWtPath);
-  const { dir, file } = _buildTaskDocPath(base, plan, {
-    taskNum: meta.taskNum,
-    slug: meta.slug,
-    promoted: !!meta.promoted,
-  });
-  if (fs.existsSync(file) && fs.readFileSync(file, 'utf8').trim()) {
-    throw new Error(`task 문서 이미 존재: ${file}`);
+// `## 제목` 절 본문(다음 `## `까지). 코드 블록 안의 `## ` 줄은 절 제목으로 보지 않는다
+function section(text, title) {
+  const lines = text.split('\n');
+  const fenced = fenceMask(lines);
+  const start = lines.findIndex((l, i) => !fenced[i] && l.trim() === `## ${title}`);
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (!fenced[i] && /^## /.test(lines[i])) break;
+    out.push(lines[i]);
   }
-  mkdirp(dir);
-  fs.writeFileSync(
-    file,
-    _renderTaskSkeleton({
-      taskNum: meta.taskNum,
-      title: meta.title,
-      created,
-      plan,
-      docType,
-      size: meta.size,
-      parent,
-    }),
-  );
-  return { registered, promoted: !!meta.promoted, plan, file };
+  return out.join('\n');
 }
 
-// ─── plan 생성 (코드화, C3) ─────────────────────────────────────────
-// 채번 + legacy 게이트 + 폴더 mkdir + ROADMAP/PLAN/BACKLOG 골격 + manifest.activePlan 갱신을 코드로.
-// LLM 몫(FEATURES/UX-UI delta · ROADMAP Stage 내용 · PLAN 링크)은 골격의 placeholder로 남긴다.
-
-function _renderRoadmap(plan) {
-  return [
-    `# ROADMAP — ${plan}`,
-    '',
-    '> 본 plan(기능 그룹) 한정 task 단계. Stage 단위(task 번호 강제 X), 상태 컬럼만 Living.',
-    '> 프로젝트 거시 빌드 순서는 PROJECT.md, 다음 기능 그룹 후보는 글로벌 BACKLOG.md.',
-    '',
-    '## Stage 1 — <영역명>',
-    '| 작업 단위 | 상태 |',
-    '|-----------|------|',
-    '| <한 task 분량 작업> | ⏳ 대기 |',
-    '',
-  ].join('\n');
+// 1.0.1 문서 = `## 개발 계획` 또는 `## 테스트 계획` 절이 있다(renderDoc이 둘 중 하나는 반드시 만든다).
+// 없으면 1.0.0 문서(목표·완료 기준·만질 파일·Phase 절)로 읽는다
+function isNewDoc(text) {
+  return section(text, '개발 계획') !== null || section(text, '테스트 계획') !== null;
 }
 
-function _renderPlanIndex(plan) {
-  return [
-    `# PLAN — ${plan}`,
-    '',
-    '> 이 plan(기능 그룹)의 얇은 인덱스. 각 항목은 루트 문서 섹션 링크 1줄 — 본문은 복제하지 않는다.',
-    '',
-    '## 이 기능 그룹이 건드리는 루트 문서',
-    '- [FEATURES.md › <이 그룹 섹션>](../../FEATURES.md) — <한 줄 요약>',
-    '- [UX-UI.md › <이 그룹 섹션>](../../UX-UI.md) — <한 줄 요약>',
-    '- (DATA-MODEL / API-SPEC — task 진행이 구현 동반으로 채움)',
-    '',
-    '## task 체크리스트',
-    '- [ ] <작업 단위> (ROADMAP Stage N)',
-    '',
-  ].join('\n');
+function meaningfulLines(body) {
+  return (body || '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
 }
 
-function _renderPlanBacklog(plan) {
-  return [
-    `# BACKLOG — ${plan}`,
-    '',
-    `> 본 파일은 *${plan} plan 진행 중 누적되는 후속 task 후보* 추적용.`,
-    '> 글로벌 `.project/BACKLOG.md` (다음 기능 그룹 후보 카탈로그) 와 별개.',
-    '',
-    '| 위치 | 영역 | 역할 |',
-    '|------|------|------|',
-    '| `.project/BACKLOG.md` (글로벌) | 다음 기능 그룹 후보 카탈로그 (다음 plan에서 검토) | Living document |',
-    `| \`.project/tasks/${plan}/BACKLOG.md\` (본 파일) | 현재 plan 진행 중 누적된 후속 task 후보 | 한 plan 내 task close 직후 후보 누적 |`,
-    '',
-    '## 후속 task 후보',
-    '',
-    BACKLOG_PLACEHOLDER,
-    '',
-  ].join('\n');
+// 경로 한 줄 → 경로. 백틱 안을 우선, 없으면 ' — ' 앞, 꼬리 괄호 주석은 뗀다
+function cleanPath(raw) {
+  let s = raw.trim();
+  const tick = s.match(/`([^`]+)`/);
+  if (tick) s = tick[1];
+  else s = s.split(/\s+—\s+|\s+-\s+/)[0];
+  return s.replace(/\s*[(（][^)）]*[)）]\s*$/, '').trim();
 }
 
-function _setActivePlan(mainWtPath, plan) {
-  // 활성 plan SSoT = manifest.activePlan (0.7.0+). 구형 AGENT-GUIDE.md는 갱신하지 않는다
-  // (읽기 폴백 전용 — 두 곳에 쓰면 다시 갈린다).
-  // manifest는 읽고-고쳐-쓰기라 다른 기록자(init/update/add)와 겹치면 필드가 유실될 수 있어 락으로 감싼다.
-  const manifestPath = path.join(mainWtPath, MANIFEST_NAME);
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`${MANIFEST_NAME} 부재. 'npx @angar2/taskery init' 먼저 실행.`);
-  }
-  withMetaLockSync(manifestPath, () => {
-    const manifest = readManifest(manifestPath);
-    if (!manifest) throw new Error(`${MANIFEST_NAME} 읽기 실패.`);
-    manifest.activePlan = plan;
-    writeManifest(manifest, manifestPath);
-  });
+function parseFileList(body) {
+  return meaningfulLines(body)
+    .filter((l) => /^[-*]\s+/.test(l))
+    .map((l) => cleanPath(l.replace(/^[-*]\s+/, '')))
+    .filter(Boolean);
 }
 
-function initPlan(mainWtPath, slug, opts = {}) {
-  // 채번 → legacy 게이트 → 폴더 + 골격 + manifest.activePlan 갱신. slug 검증은 CLI 측.
-  // legacy 폴더(NNN_ 아닌 plan 폴더) 잔존 + !force → { gated:true } 반환(CLI가 사용자 confirm 후 force 재호출).
-  const { next, legacyDirs } = computeNextPlanNumber(mainWtPath);
-  if (legacyDirs.length && !opts.force) {
-    return { gated: true, legacyDirs, next };
-  }
-  const plan = `${next}_${slug}`;
-  const planDir = path.join(mainWtPath, '.project', 'plans', plan);
-  const tasksDir = path.join(mainWtPath, '.project', 'tasks', plan);
-  if (fs.existsSync(planDir)) {
-    throw new Error(`plan 폴더 이미 존재: ${planDir}`);
-  }
-  mkdirp(planDir);
-  mkdirp(path.join(tasksDir, 'spec-diffs'));
-  mkdirp(path.join(tasksDir, 'screenshots'));
-  mkdirp(path.join(tasksDir, 'mockup'));
-  fs.writeFileSync(path.join(planDir, 'ROADMAP.md'), _renderRoadmap(plan));
-  fs.writeFileSync(path.join(planDir, 'PLAN.md'), _renderPlanIndex(plan));
-  fs.writeFileSync(path.join(tasksDir, 'BACKLOG.md'), _renderPlanBacklog(plan));
-  _setActivePlan(mainWtPath, plan);
-  return { gated: false, plan, nnn: next, planDir, tasksDir, legacyDirs };
-}
-
-// ─── task close 결정적 준비 (코드화, D1·D2) ─────────────────────────
-// closeTask는 *결정적 준비만* 수행: 게이트(status=tested) → Phase 커밋(D2) → status=closed →
-// flows/문서 커밋 → 추적마커. 비가역 3종(부모 브랜치 --no-ff 머지 · worktree remove · branch -d)과
-// 충돌 해결·머지 락은 스킬(LLM)이 수행 — 위험 최소화 + 충돌은 LLM 판단 영역.
-
-// 브랜치 타입 → 커밋 태그 (GIT_RULE 6-3).
-const TAG_OF = {
-  feature: 'feat',
-  bug: 'fix',
-  improve: 'improve',
-  refactor: 'refactor',
-  docs: 'docs',
-  chore: 'docs',
-};
-
-function _parseDevPlanPhases(content) {
-  // ## Dev Plan 섹션의 `### Phase N — 이름` + `- 파일:` 필드 추출.
-  // 다중 파일 표기 지원 — 한 줄(쉼표·가운뎃점 `·` 구분) + `- 파일:` 다음의 들여쓴 하위 목록.
-  // `/`는 경로 문자라 분할자로 쓰지 않는다. `(신규)`류 꼬리 괄호 주석은 제거한다.
-  const lines = content.split('\n');
-  let inDevPlan = false;
+// Phase: `### Phase N — 이름` + `- 파일:`(한 줄 쉼표·가운뎃점 구분 또는 들여쓴 목록) + `- 사유:`
+// 1.0.1 문서는 `## 개발 계획` 안에, 1.0.0 문서는 `## Phase` 절에 있다
+function parsePhases(text) {
+  const body = section(text, isNewDoc(text) ? '개발 계획' : 'Phase');
+  if (!body) return [];
   const phases = [];
   let cur = null;
-  let fileIndent = null; // `- 파일:` 줄의 들여쓰기 — 이보다 깊은 목록 항목을 파일로 수집
-  const pushFiles = (raw) => {
-    for (const piece of raw.split(/[,·]/)) {
-      const f = piece
-        .replace(/`/g, '')
-        .trim()
-        .replace(/\s*[(（][^)）]*[)）]\s*$/, ''); // 꼬리 괄호 주석 제거
-      if (f && !/^[(<]/.test(f)) cur.files.push(f); // placeholder(<...>, (...)) 제외
-    }
-  };
-  for (const l of lines) {
-    if (/^##\s+Dev Plan/.test(l)) {
-      inDevPlan = true;
-      continue;
-    }
-    if (inDevPlan && /^##\s+/.test(l)) break; // 다음 섹션
-    if (!inDevPlan) continue;
-    const ph = l.match(/^###\s+Phase\s+(\d+)\s*(?:[—-]\s*)?(.*)$/);
+  let fileIndent = null;
+  for (const l of body.split('\n')) {
+    const ph = l.match(/^###\s+Phase\s+(\d+)\s*(?:[—–-]\s*)?(.*)$/);
     if (ph) {
-      cur = { num: parseInt(ph[1], 10), name: ph[2].trim(), files: [] };
+      cur = { num: parseInt(ph[1], 10), name: ph[2].trim(), files: [], reason: '' };
       phases.push(cur);
       fileIndent = null;
       continue;
     }
     if (!cur) continue;
-    const fm = l.match(/^(\s*)-\s*파일\s*:\s*(.*)$/);
+    const fm = l.match(/^(\s*)[-*]\s*파일\s*:\s*(.*)$/);
     if (fm) {
       fileIndent = fm[1].length;
-      if (fm[2].trim()) pushFiles(fm[2]);
+      for (const p of fm[2].split(/[,·]/)) if (cleanPath(p)) cur.files.push(cleanPath(p));
+      continue;
+    }
+    const rm = l.match(/^\s*[-*]\s*사유\s*:\s*(.*)$/);
+    if (rm) {
+      cur.reason = rm[1].trim();
+      fileIndent = null;
       continue;
     }
     if (fileIndent != null) {
-      const sub = l.match(/^(\s+)-\s+(.+)$/);
+      const sub = l.match(/^(\s+)[-*]\s+(.+)$/);
       if (sub && sub[1].length > fileIndent) {
-        pushFiles(sub[2]);
+        if (cleanPath(sub[2])) cur.files.push(cleanPath(sub[2]));
         continue;
       }
-      fileIndent = null; // 다른 필드·비목록 줄에서 하위 목록 수집 종료
+      fileIndent = null;
     }
   }
   return phases;
 }
 
-function _porcelainFiles(wtPath) {
-  // git status --porcelain -uall → 변경 파일 경로 목록 (XY 상태코드 3자 제거).
-  // -uall: untracked 디렉토리를 개별 파일로 전개 (디렉토리 통째 `src/` 접힘 방지).
-  const out = gitCapture(wtPath, ['status', '--porcelain', '-uall'], { allowFail: true });
-  if (!out) return [];
-  return out
-    .split('\n')
-    .filter(Boolean)
-    .map((l) => l.slice(3).trim())
-    .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p)) // rename은 도착 경로
-    .filter(Boolean);
+// 완료 기준 — `[AUTO]`·`[USER]`가 붙은 줄을 차례로 1번부터 센다
+function parseCriteria(text) {
+  return meaningfulLines(section(text, isNewDoc(text) ? '테스트 계획' : '완료 기준')).filter((l) =>
+    /^(?:\d+[.)]|[-*])\s*\[(AUTO|USER)\]/.test(l),
+  );
 }
 
-// 빌드 산출물 판정 — 소스 변경에 도구가 따라 바꾸는 파생 파일 (Phase 소속을 묻는 것 자체가 무의미).
-// Dev Plan에 명시 안 돼도 미매핑 blocked 대신 마지막 Phase에 자동 편입 (stash·recordion FRICTION: pbxproj 미매핑만 6회).
-const BUILD_ARTIFACT_RE = [
-  /\.pbxproj$/,
-  /(^|\/)package-lock\.json$/,
-  /(^|\/)yarn\.lock$/,
-  /(^|\/)pnpm-lock\.yaml$/,
-  /(^|\/)Cargo\.lock$/,
-  /(^|\/)Gemfile\.lock$/,
-  /(^|\/)Podfile\.lock$/,
-];
-
-function splitUncommittedByPhase(wtPath, taskMdPath, meta) {
-  // 코드 변경분(.project/ 외)을 Dev Plan Phase에 매핑해 Phase별 자동 커밋. meta: { taskNum, type }.
-  // 매핑 폴백 3규칙 (stash 6회 + recordion 5회 blocked 마찰 반영 — 11회 전부 기계적 편입이었음):
-  //   1. 다중 Phase 매핑 → 가장 이른 Phase에 편입 + 커밋 메시지에 '(Phase a·b 변경 포함)' 표기.
-  //      뒤 Phase가 앞 Phase 타입·함수를 참조하므로 이른 쪽이 의존 방향과 일치. 중간 커밋 독립 빌드는 비보장(GIT_RULE 명문).
-  //   2. 미매핑 + 빌드 산출물(BUILD_ARTIFACT_RE) → 매핑된 그룹 중 마지막 Phase(없으면 Dev Plan 마지막)에
-  //      자동 편입 + '(빌드 산출물 자동 편입)' 표기.
-  //   3. 미매핑 + 일반 파일 → { ambiguous } 반환(커밋 X) — 계획 누락 가능성이라 사람 판단으로 유지.
-  // .project/ 메타(flows/문서/changelog)는 제외 — closeTask가 별도 커밋.
-  const codeFiles = _porcelainFiles(wtPath).filter((f) => !f.startsWith('.project/'));
-  if (codeFiles.length === 0) return { committed: [], empty: true };
-  const phases = _parseDevPlanPhases(fs.readFileSync(taskMdPath, 'utf8'));
-  if (phases.length === 0) {
-    return { ambiguous: true, reason: 'Dev Plan Phase 파싱 불가', files: codeFiles };
-  }
-  const matchOf = (f) =>
-    phases
-      .map((p, i) => ({ p, i }))
-      .filter(({ p }) =>
-        p.files.some((pf) => {
-          const base = pf.replace(/\/$/, '');
-          return f === pf || f === base || f.startsWith(base + '/') || base.endsWith('/' + f);
-        }),
-      )
-      .map(({ i }) => i);
-  const fileToPhase = {};
-  const multiPhase = []; // 규칙 1 적용분 — { file, phases:[num...], assignedTo }
-  const artifactFiles = []; // 규칙 2 후보 — 매핑 확정 후 편입 Phase 결정
-  for (const f of codeFiles) {
-    const m = matchOf(f);
-    if (m.length === 1) {
-      fileToPhase[f] = m[0];
-    } else if (m.length > 1) {
-      const earliest = Math.min(...m);
-      fileToPhase[f] = earliest;
-      multiPhase.push({ file: f, phases: m.map((i) => phases[i].num), assignedTo: phases[earliest].num });
-    } else if (BUILD_ARTIFACT_RE.some((re) => re.test(f))) {
-      artifactFiles.push(f);
-    } else {
-      return {
-        ambiguous: true,
-        reason: `Phase 미매핑: ${f}`,
-        files: codeFiles,
-        phases: phases.map((p) => ({ num: p.num, name: p.name, files: p.files })),
-      };
-    }
-  }
-  // 규칙 2 — 산출물 편입: 매핑된 그룹 중 마지막 Phase, 하나도 없으면 Dev Plan 마지막 Phase
-  const autoAssigned = [];
-  if (artifactFiles.length > 0) {
-    const mappedIdx = Object.values(fileToPhase);
-    const lastIdx = mappedIdx.length > 0 ? Math.max(...mappedIdx) : phases.length - 1;
-    for (const f of artifactFiles) {
-      fileToPhase[f] = lastIdx;
-      autoAssigned.push({ file: f, assignedTo: phases[lastIdx].num });
-    }
-  }
-  // 파일별 커밋 메시지 표기 (자동 편입의 근거를 커밋에 남김 — 코드가 몰래 정한 걸 드러낸다)
-  const noteOf = {};
-  for (const x of multiPhase) noteOf[x.file] = ` (Phase ${x.phases.join('·')} 변경 포함)`;
-  for (const x of autoAssigned) noteOf[x.file] = ' (빌드 산출물 자동 편입)';
-  // Phase별 그룹 → 순서대로 커밋
-  const groups = new Map();
-  for (const f of Object.keys(fileToPhase)) {
-    const i = fileToPhase[f];
-    if (!groups.has(i)) groups.set(i, []);
-    groups.get(i).push(f);
-  }
-  const tag = TAG_OF[meta.type] || 'docs';
-  const nnn = String(meta.taskNum).padStart(3, '0');
-  const committed = [];
-  for (const i of [...groups.keys()].sort((a, b) => a - b)) {
-    const p = phases[i];
-    const grp = groups.get(i);
-    execFileSync('git', ['-C', wtPath, 'add', '--', ...grp], { stdio: 'pipe' });
-    const msg =
-      `${tag}: [TASK-${nnn}] Phase ${p.num} - ${p.name}\n\n` +
-      grp.map((f) => `- ${f}${noteOf[f] || ''}`).join('\n') +
-      `\n- 사유: ${p.name}`;
-    execFileSync('git', ['-C', wtPath, 'commit', '-m', msg], { stdio: 'pipe' });
-    committed.push({ phase: p.num, name: p.name, files: grp });
+// 목표 = 1.0.1은 `## 요구사항` 첫 줄, 1.0.0은 `## 목표` 첫 줄(1.0.0 medium은 두 절이 다 있다)
+function goalLine(text) {
+  return meaningfulLines(section(text, isNewDoc(text) ? '요구사항' : '목표'))[0] || '';
+}
+
+// approve-plan의 목표 검사 — 문제가 없으면 null
+function goalProblem(text) {
+  const goal = goalLine(text);
+  if (!isNewDoc(text)) return goal ? null : '`## 목표`가 비어 있다';
+  if (!goal) return '`## 요구사항` 첫 줄(목표)이 비어 있다 — 무엇을 왜 하는지 한 문장';
+  if (/^(?:[-*]|\d+[.)])\s/.test(goal)) return '`## 요구사항` 첫 줄은 목록 기호 없는 목표 한 문장이어야 한다(무엇을 왜) — 요구 목록은 그 아래에';
+  return null;
+}
+
+// 계획 파일 — 1.0.1은 `## 개발 계획`의 Phase `- 파일:`(Phase가 있으면 그것만), 없으면 목록.
+// 1.0.0은 `## 만질 파일` + `## Phase`
+function plannedFiles(text) {
+  if (isNewDoc(text)) {
+    const phases = parsePhases(text);
+    if (!phases.length) return parseFileList(section(text, '개발 계획'));
+    const files = [];
+    for (const p of phases) for (const f of p.files) if (!files.includes(f)) files.push(f);
+    return files;
+  }
+  const files = parseFileList(section(text, '만질 파일'));
+  for (const p of parsePhases(text)) for (const f of p.files) if (!files.includes(f)) files.push(f);
+  return files;
+}
+
+// 경로가 계획 목록(파일 또는 폴더)에 들어 있나
+function fileMatches(file, planned) {
+  const base = planned.replace(/\/$/, '');
+  return file === base || file.startsWith(base + '/');
+}
+
+// ─── 헤더 표 ────────────────────────────────────────
+
+const HEADER_HEAD = '| 생성일 | 플랜 | 유형 | 크기 | 스위치 | 범위 | 부모 브랜치 | 브랜치 | 상태 |';
+const HEADER_SEP = '|---|---|---|---|---|---|---|---|---|';
+const SWITCH_LABEL = { plan: '기획', dev: '개발', test: '테스트' };
+
+function cell(v) {
+  return String(v == null ? '' : v).replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
+}
+
+function renderHeaderRow(st) {
+  const cells = [
+    clock(st.times.prepare).slice(0, 10),
+    st.item ? `${st.plan} (항목 ${st.item})` : st.plan,
+    st.type,
+    st.size,
+    ['plan', 'dev', 'test'].filter((n) => sw(st, n)).map((n) => SWITCH_LABEL[n]).join('·'),
+    st.range,
+    st.parent,
+    st.noBranch ? '분기 없음' : st.branch,
+    !st.closed ? '열림' : st.closed.finished ? '닫힘(완료)' : '닫힘(포기)',
+  ];
+  return `| ${cells.map(cell).join(' | ')} |`;
+}
+
+// ─── 시간 · 단계 표 ─────────────────────────────────
+
+function ms(iso) {
+  return iso ? new Date(iso).getTime() : null;
+}
+
+function minutes(msVal) {
+  if (msVal == null) return '';
+  const m = Math.round(msVal / 60000);
+  return m < 1 ? '1분 미만' : `${m}분`;
+}
+
+// 단계별 소요 시간(ms). 각 단계 = 그 단계 완료 시각 − 앞 단계들의 마지막 완료 시각
+function stageDurations(st) {
+  const t0 = ms(st.times.prepare);
+  const tPlan = st.approve ? ms(st.approve.at) : null;
+  const tDev = sw(st, 'dev') && st.testCode ? ms(st.testCode.at) : null;
+  const tTest = sw(st, 'test') && st.testDone ? ms(st.testDone.at) : null;
+  const tClose = st.closed ? ms(st.closed.at) : null;
+  const d = {};
+  if (tPlan != null) d.plan = Math.max(0, tPlan - t0);
+  if (tDev != null) d.dev = Math.max(0, tDev - Math.max(t0, tPlan || t0));
+  if (tTest != null) d.test = Math.max(0, tTest - Math.max(t0, tPlan || t0, tDev || t0));
+  if (tClose != null) {
+    let close = tClose - Math.max(t0, tPlan || t0, tDev || t0, tTest || t0);
+    // 병합 확인 대기(commit-task 끝 ~ merge-task 시작)는 뺀다(§4-3)
+    if (st.commit && st.mergeStart) close -= Math.max(0, ms(st.mergeStart) - ms(st.commit.at));
+    d.close = Math.max(0, close);
+    d.total = (d.plan || 0) + (d.dev || 0) + (d.test || 0) + d.close;
+  }
+  return d;
+}
+
+function stageCells(st) {
+  const d = stageDurations(st);
+  const planDone = !!st.approve;
+  const devDone = !sw(st, 'dev') || !!st.testCode;
+  const testDone = !sw(st, 'test') || !!st.testDone;
+  const cells = [];
+  cells.push(planDone ? `✅ ${minutes(d.plan)}` : '⏳');
+  if (!sw(st, 'dev')) cells.push('꺼짐');
+  else cells.push(st.testCode ? `✅ ${minutes(d.dev)}` : planDone ? '⏳' : '–');
+  if (!sw(st, 'test')) cells.push('꺼짐');
+  else if (st.testDone) cells.push(`✅ ${minutes(d.test)}${st.testDone.accepted ? ' (FAIL 수락)' : ''}`);
+  else cells.push(planDone && devDone ? '⏳' : '–');
+  if (st.closed) cells.push(`✅ ${minutes(d.close)} (합계 ${minutes(d.total)})`);
+  else cells.push(planDone && devDone && testDone ? '⏳' : '–');
+  return cells;
+}
+
+const TABLE_HEAD = '| 시작·기획 | 개발 | 테스트 | 닫기 |';
+
+function renderTableRow(st) {
+  return `| ${stageCells(st).join(' | ')} |`;
+}
+
+// 문서 머리(첫 `## ` 앞)에서 표 머리 줄을 찾는다
+function headIndex(lines, head) {
+  let end = lines.findIndex((l) => /^## /.test(l));
+  if (end === -1) end = lines.length;
+  for (let i = 0; i < end; i++) {
+    if (lines[i].trim() === head) return lines[i + 2] !== undefined && i + 2 < end && lines[i + 2].trim().startsWith('|') ? i : -1;
   }
-  const result = { committed };
-  if (multiPhase.length > 0) result.multiPhase = multiPhase;
-  if (autoAssigned.length > 0) result.autoAssigned = autoAssigned;
-  return result;
-}
-
-// ─── close 문서 자동화 (recordion FRICTION 2026-08-09 — 문서 갱신 기계화) ─────────
-// CHANGELOG는 close가 직접 append(세션 준수 불요), PLAN 체크·수정이력은 grep 게이트로 차단.
-
-function _parseTaskTitle(taskMdPath) {
-  // task 문서 H1 → 제목 (`# TASK-NNN — 제목`의 제목부. 접두 없으면 전체).
-  const m = fs.readFileSync(taskMdPath, 'utf8').match(/^#\s+(.+)$/m);
-  if (!m) return null;
-  return m[1].replace(/^TASK-\d+\s*[—-]\s*/, '').trim() || null;
-}
-
-function appendChangelogEntry(base, { taskNum, title, type, phases }) {
-  // CHANGELOG 항목을 close가 직접 append — CHANGELOG_RULE §1 두 형식(단일 CHANGELOG.md / 월별) 지원,
-  // 없으면 월별 파일 생성. 최신 맨 위 삽입(§3). 재호출 가드: [TASK-NNN] 실재 시 skip
-  // (mapping·docs 콜백 후 재호출 중복 차단). base = task 문서와 동일 분기(등록=메인WT / 미등록=워크트리).
-  const nnn = String(taskNum).padStart(3, '0');
-  const dir = path.join(base, '.project', 'changelog');
-  const single = path.join(dir, 'CHANGELOG.md');
-  const file = fs.existsSync(single) ? single : path.join(dir, `${_todayLocal().slice(0, 7)}.md`);
-  const exists = fs.existsSync(file);
-  const cur = exists ? fs.readFileSync(file, 'utf8') : '';
-  if (cur.includes(`[TASK-${nnn}]`)) return { file, skipped: true };
-  const named = (phases || []).filter((p) => p.num > 0 && p.name);
-  const summary = named.length
-    ? named.map((p) => `  - Phase ${p.num} — ${p.name}`).join('\n')
-    : `  - ${title || `TASK-${nnn}`}`;
-  const entry = [
-    `## [TASK-${nnn}] ${title || ''}`.trimEnd(),
+  return -1;
+}
+
+// 문서의 헤더 표와 단계 표 줄을 .state 기록으로 다시 쓴다(두 표는 명령만 쓴다).
+// 1.0.0 문서는 제목 바로 아래 메타 줄을 헤더 표로 바꾼다
+function syncDoc(main, st) {
+  const file = docAbs(main, st);
+  if (!fs.existsSync(file)) return;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  if (headIndex(lines, HEADER_HEAD) === -1 && lines[1] !== undefined && lines[1].startsWith('<!-- taskery:')) {
+    lines.splice(1, 1, '', HEADER_HEAD, HEADER_SEP, renderHeaderRow(st));
+  }
+  const hi = headIndex(lines, HEADER_HEAD);
+  if (hi !== -1) lines[hi + 2] = renderHeaderRow(st);
+  const ti = headIndex(lines, TABLE_HEAD);
+  if (ti !== -1) lines[ti + 2] = renderTableRow(st);
+  fs.writeFileSync(file, lines.join('\n'));
+}
+
+function renderDoc(st) {
+  const out = [
+    `# ${taskLabel(st.num)} ${st.title}`,
     '',
-    `- **날짜**: ${_todayLocal()}`,
-    `- **타입**: ${type}`,
-    `- **변경 요약**:`,
-    summary,
-  ].join('\n');
-  let next;
-  if (!exists) {
-    fs.mkdirSync(dir, { recursive: true });
-    next = entry + '\n';
-  } else {
-    // 첫 `## ` 항목 바로 위 삽입 (코드펜스 내부 제외). 항목이 없으면 헤더 뒤(끝) append.
-    const lines = cur.split('\n');
-    let fence = false;
-    let idx = -1;
-    for (let i = 0; i < lines.length; i++) {
-      if (/^\s*(```|~~~)/.test(lines[i])) fence = !fence;
-      else if (!fence && /^##\s+/.test(lines[i])) {
-        idx = i;
-        break;
-      }
-    }
-    if (idx === -1) {
-      next = cur + (cur.endsWith('\n') ? '' : '\n') + '\n' + entry + '\n';
-    } else {
-      lines.splice(idx, 0, entry, '');
-      next = lines.join('\n');
-    }
-  }
-  fs.writeFileSync(file, next);
-  return { file, added: true };
-}
-
-function checkDocsGate(base, { taskNum, src, plan }) {
-  // 문서 게이트 — close의 모든 변이(mutation) 앞에서 실행. blocked여도 아무것도 안 바뀌어
-  // 세션이 문서를 채운 후 그대로 재호출하면 된다. 반환 { ok:true } | { ok:false, missing:[...] }.
-  //   PLAN.md: 로드맵 출처(ST-/RM-)만 — 체크리스트에 TASK-NNN 표기 검사. BL·DR 출처는 항목
-  //   자체가 없으므로 통과. 파일 부재(구형 plan)도 통과.
-  //   수정이력: spec-diffs(항상 plan 폴더 공통 — 폴더 승격 무관, TASK_DOC_RULE §1.5)의 본 태스크
-  //   파일이 가리키는 대상 문서(DEL 제외)에 TASK-NNN 표기 검사. 대상 부재 = 통과
-  //   (게이트 실패 방향은 '막는 쪽'이 아니라 '놓치는 쪽' — 정당한 close를 오차단하지 않는다).
-  const nnn = String(taskNum).padStart(3, '0');
-  const tag = `TASK-${nnn}`;
-  const missing = [];
-  if (/^(ST|RM)-/i.test(src || '')) {
-    const planPath = path.join(base, '.project', 'plans', plan, 'PLAN.md');
-    if (fs.existsSync(planPath) && !fs.readFileSync(planPath, 'utf8').includes(tag)) {
-      missing.push({ kind: 'plan', file: planPath });
-    }
-  }
-  const specDir = path.join(base, '.project', 'tasks', plan, 'spec-diffs');
-  if (fs.existsSync(specDir)) {
-    const seen = new Set();
-    const mine = fs
-      .readdirSync(specDir)
-      .filter((f) => f.startsWith(`${nnn}_`) && f.endsWith('.md'));
-    for (const f of mine) {
-      const content = fs.readFileSync(path.join(specDir, f), 'utf8');
-      // 헤딩 `## <.project/문서.md> [NEW|MOD|DEL]` — 꺾쇠 유무 관용 파싱
-      for (const m of content.matchAll(/^##\s+<?([^\n>[\]]+?)>?\s*\[(NEW|MOD|DEL)\]/gm)) {
-        if (m[2] === 'DEL') continue;
-        const rel = m[1].trim();
-        const target = fs.existsSync(path.join(base, rel))
-          ? path.join(base, rel)
-          : path.join(base, '.project', rel);
-        if (seen.has(target)) continue;
-        seen.add(target);
-        if (!fs.existsSync(target)) continue; // 대상 부재 → 통과
-        if (!fs.readFileSync(target, 'utf8').includes(tag)) {
-          missing.push({ kind: 'history', file: target });
-        }
-      }
+    HEADER_HEAD,
+    HEADER_SEP,
+    renderHeaderRow(st),
+    '',
+    TABLE_HEAD,
+    '|---|---|---|---|',
+    renderTableRow(st),
+    '',
+    '## 요구사항',
+    '',
+  ];
+  if (sw(st, 'dev')) out.push('## 개발 계획', '');
+  if (sw(st, 'test')) out.push('## 테스트 계획', '');
+  out.push('## 결정', '', '## 결과', '');
+  return out.join('\n');
+}
+
+// `## 결과` 절 끝에 한 줄을 붙인다(명령만 쓴다). 문서가 없으면 아무것도 하지 않는다
+function appendResult(main, st, line) {
+  const file = docAbs(main, st);
+  if (!fs.existsSync(file)) return;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  const fenced = fenceMask(lines);
+  let start = lines.findIndex((l, i) => !fenced[i] && l.trim() === '## 결과');
+  if (start === -1) {
+    while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+    lines.push('', '## 결과', '');
+    start = lines.length - 2;
+  }
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (!fenced[i] && /^## /.test(lines[i])) {
+      end = i;
+      break;
     }
   }
-  return missing.length ? { ok: false, missing } : { ok: true };
-}
-
-async function closeTask(mainWtPath, { taskNum }, opts = {}) {
-  // 결정적 준비만 — 비가역(머지·정리)·충돌 해결은 스킬이 후속 수행.
-  // 순서: status 게이트 → docs 게이트 → Phase 커밋 → setStatus(closed) → CHANGELOG append
-  //       → (미등록) .project/ 커밋 → 추적 마커. 게이트 2종은 모든 변이 앞.
-  // 반환: { blocked } (status/docs 게이트 미충족·매핑 모호) 또는
-  //   { prepped, branch, parent, wtPath, registered, commits, aheadOfParent, changelog,
-  //     multiPhase?, autoAssigned? (매핑 폴백 적용 시 내역) }. parent = 스킬 머지 대상.
-  const active = getActiveTasks(mainWtPath).find((t) => t.taskNum === taskNum);
-  if (!active) {
-    throw new Error(`TASK-${String(taskNum).padStart(3, '0')} 진행중 브랜치 없음 (SSoT 조회).`);
-  }
-  const projectId = getProjectId(mainWtPath);
-  const wtPath = getWorktreePath(projectId, { taskNum, src: active.src, slug: active.slug });
-  const resolved = resolveTaskDocPath(mainWtPath, wtPath, { taskNum });
-  if (!resolved) throw new Error(`TASK-${taskNum} 문서 못 찾음.`);
-
-  const header = parseTaskHeader(resolved.file);
-  // 부모 = 헤더 기록값(0.6.0, 구 문서는 'dev' 폴백). 메인 워크트리가 그 부모에 서 있어야
-  // 스킬 후속 머지가 올바른 브랜치로 간다.
-  const parent = header.parent;
-  assertMainWorktreeOn(mainWtPath, parent);
-  if (header.status !== 'tested') {
-    return { blocked: 'status', current: header.status, docPath: resolved.file };
-  }
-
-  // 문서 게이트 — 모든 변이 앞. blocked 시 아무 것도 안 바뀌어 채우고 그대로 재호출.
-  const docBase = resolved.registered ? mainWtPath : wtPath;
-  const gate = checkDocsGate(docBase, { taskNum, src: active.src, plan: resolved.plan });
-  if (!gate.ok) {
-    return { blocked: 'docs', missing: gate.missing, docPath: resolved.file };
-  }
-
-  // Phase 커밋 (D2) — 코드 변경분만
-  const split = splitUncommittedByPhase(wtPath, resolved.file, { taskNum, type: active.type });
-  if (split.ambiguous) {
-    return {
-      blocked: 'mapping',
-      reason: split.reason,
-      files: split.files,
-      phases: split.phases,
-      wtPath,
-      docPath: resolved.file,
-    };
+  let at = end;
+  while (at > start + 1 && lines[at - 1].trim() === '') at--;
+  if (at === start + 1) {
+    lines.splice(at, 0, '', line);
+  } else {
+    lines.splice(at, 0, line);
   }
+  fs.writeFileSync(file, lines.join('\n'));
+}
 
-  // status=closed (문서 위치 무관 — setStatus가 .gitignore 케이스 따라 처리)
-  await setStatus(resolved.file, 'closed');
-
-  // CHANGELOG 자동 append — 등록=메인WT 직접 쓰기(.project는 gitignore라 커밋 불요) /
-  // 미등록=워크트리 쓰기(아래 .project/ 문서 커밋이 함께 수거).
-  const changelog = appendChangelogEntry(docBase, {
-    taskNum,
-    title: _parseTaskTitle(resolved.file),
-    type: header.type,
-    phases: _parseDevPlanPhases(fs.readFileSync(resolved.file, 'utf8')),
-  });
+function nowIso() {
+  return new Date().toISOString();
+}
 
-  const commits = [...split.committed];
-  // 미등록 케이스: .project/ 변경분(flows / 문서 / changelog)을 커밋
-  if (!resolved.registered) {
-    const flows = _porcelainFiles(wtPath).filter((f) => f.startsWith('.project/flows/'));
-    if (flows.length) {
-      execFileSync('git', ['-C', wtPath, 'add', '--', ...flows], { stdio: 'pipe' });
-      execFileSync(
-        'git',
-        ['-C', wtPath, 'commit', '-m', `docs: [TASK-${String(taskNum).padStart(3, '0')}] flows 갱신`],
-        { stdio: 'pipe' },
-      );
-      commits.push({ phase: 'flows', files: flows });
-    }
-    const rest = _porcelainFiles(wtPath).filter((f) => f.startsWith('.project/'));
-    if (rest.length) {
-      execFileSync('git', ['-C', wtPath, 'add', '--', ...rest], { stdio: 'pipe' });
-      execFileSync(
-        'git',
-        [
-          '-C',
-          wtPath,
-          'commit',
-          '-m',
-          `docs: [TASK-${String(taskNum).padStart(3, '0')}] 태스크 문서 완료`,
-        ],
-        { stdio: 'pipe' },
-      );
-      commits.push({ phase: 'doc', files: rest });
-    }
-  }
+function clock(iso) {
+  const d = new Date(iso);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
 
-  // 추적 마커 빈커밋 (부모보다 앞선 커밋 0개 — docs/분석 task + .project gitignore 케이스)
-  const ahead = parseInt(
-    gitCapture(wtPath, ['rev-list', '--count', `${parent}..HEAD`], { allowFail: true }) || '0',
-    10,
-  );
-  if (ahead === 0) {
-    execFileSync(
-      'git',
-      [
-        '-C',
-        wtPath,
-        'commit',
-        '--allow-empty',
-        '-m',
-        `docs: [TASK-${String(taskNum).padStart(3, '0')}] 추적 마커 — 코드 0·.project gitignore (채번 보존)`,
-      ],
-      { stdio: 'pipe' },
-    );
-    commits.push({ phase: 'marker', empty: true });
-  }
+function todayLocal() {
+  return clock(nowIso()).slice(0, 10);
+}
 
-  const aheadFinal = parseInt(
-    gitCapture(wtPath, ['rev-list', '--count', `${parent}..HEAD`], { allowFail: true }) || '0',
-    10,
-  );
-  const prepResult = {
-    prepped: true,
-    taskNum,
-    branch: active.branch,
-    parent,
-    wtPath,
-    registered: resolved.registered,
-    docPath: resolved.file,
-    commits,
-    aheadOfParent: aheadFinal,
-    changelog,
-  };
-  // 매핑 폴백 적용 내역 노출 — 코드가 자동 편입한 걸 스킬·사용자가 볼 수 있게
-  if (split.multiPhase) prepResult.multiPhase = split.multiPhase;
-  if (split.autoAssigned) prepResult.autoAssigned = split.autoAssigned;
-  return prepResult;
+// 범위 갱신 — 태스크 명령에 --range를 붙이면 헤더 표의 범위 칸만 바꾼다(§3-5)
+function updateRange(main, st, range) {
+  if (!range || range === st.range) return st;
+  st.range = range;
+  writeState(main, st);
+  syncDoc(main, st);
+  return st;
 }
 
 module.exports = {
-  LOCAL_SUFFIX,
   MANIFEST_NAME,
-  // 멀티 플랫폼 (0.2.0+)
-  PLATFORMS,
-  DEFAULT_PLATFORMS,
-  SHARED_DEST,
-  platformOf,
-  mapSharedDest,
-  resolveInstallPlan,
-  GITIGNORE_PATTERNS,
-  gitignorePatternsFor,
-  findTemplateDir,
-  sha256,
-  sha256Text,
-  walkTemplate,
-  mkdirp,
-  copyFile,
-  writeManifest,
+  EXCLUDE_NAMES,
+  PLANT_COPY,
+  PLANT_LINK,
+  TYPES,
+  SIZES,
+  SWITCHES,
+  DEFAULT_RANGE,
+  TAG_OF,
+  CODE_TEST_NOTICE_MS,
+  TaskeryError,
+  fail,
+  git,
+  gitOk,
+  findMain,
+  currentBranch,
+  changedFiles,
+  trackedChanges,
+  isAncestor,
+  branchExists,
+  fingerprint,
+  ensureExclude,
+  inOrca,
+  runShell,
+  tail,
+  OLD_MANIFEST_NAME,
+  checkLegacyInstall,
   readManifest,
-  isLocalOverride,
+  writeManifest,
+  requireInstalled,
   getPackageVersion,
-  // 멀티세션 (0.1.2+)
-  TASKERY_HOME,
-  DEFAULT_STALE_DAYS,
-  DEFAULT_LOCK_TIMEOUT_MS,
-  BRANCH_PATTERNS,
-  generateProjectId,
-  gitCapture,
-  getMainWorktreePath,
-  getProjectId,
-  getWorktreesRoot,
-  getWorktreePath,
-  getMergeLockPath,
-  getInitLockPath,
-  withMergeLock,
-  withMetaLock,
-  withMetaLockSync,
-  currentBranch,
-  assertMainWorktreeOn,
-  parseBranchName,
-  getActiveTasks,
-  getNextTaskNumber,
-  forkTask,
-  computeNextPlanNumber,
-  // 백로그 (0.1.2+)
-  BACKLOG_PLACEHOLDER,
-  getActiveVersion,
-  setActivePlan,
-  getBacklogPath,
-  computeNextBLNumber,
-  formatBacklogBlock,
-  appendBacklogItem,
-  parseBacklogItem,
-  markBacklogChecked,
-  // task 헤더 / 상태 전이 (코드화)
-  TRANSITIONS,
-  parseTaskHeader,
-  isProjectRegistered,
-  resolveTaskDocPath,
-  setStatus,
-  // task 문서 골격 (C1)
-  DOC_TYPE_OF,
-  scaffoldTaskDoc,
-  // plan 생성 (C3)
-  initPlan,
-  // task close 결정적 준비 (D1·D2)
-  TAG_OF,
-  splitUncommittedByPhase,
-  appendChangelogEntry,
-  checkDocsGate,
-  closeTask,
+  stateDir,
+  pad,
+  taskLabel,
+  parseTaskNum,
+  writeJsonAtomic,
+  readState,
+  writeState,
+  listStates,
+  withLock,
+  sw,
+  needsNoMerge,
+  hasFinishRecord,
+  workDir,
+  parseGitRuleTable,
+  readGitRule,
+  fillTemplate,
+  docAbs,
+  docShown,
+  readDoc,
+  section,
+  isNewDoc,
+  meaningfulLines,
+  parseFileList,
+  parsePhases,
+  parseCriteria,
+  goalLine,
+  goalProblem,
+  plannedFiles,
+  fileMatches,
+  renderHeaderRow,
+  stageDurations,
+  stageCells,
+  minutes,
+  syncDoc,
+  renderDoc,
+  appendResult,
+  nowIso,
+  clock,
+  todayLocal,
+  updateRange,
 };