@angar2/taskery 0.6.1 → 0.7.0

package/README.md

@@ -108,7 +108,8 @@ taskery prune
 
 ```
 my-app/
-├─ CLAUDE.md                              # AI 에이전트 진입 문서
+├─ AGENTS.md                              # AI 에이전트 진입 문서 (본문 단일 소스)
+├─ CLAUDE.md                              # Claude Code용 — `@AGENTS.md` 임포트 한 줄
 ├─ .taskery-manifest.json                 # 패키지 업데이트 추적
 ├─ .gitignore
 ├─ .claude/
@@ -117,19 +118,19 @@ my-app/
 │   └─ hooks/<hook-name>.sh               # 2 hook
 └─ .project/
     ├─ PROJECT.md                         # 프로젝트 개요
-    ├─ AGENT-GUIDE.md                     # AI 에이전트 가이드
     ├─ LINKED-REPOS.md                    # 관계 리포지토리 정보
     ├─ GLOSSARY.md                        # 도메인 용어집 (영문/한글 표기 일관성)
     ├─ .env                               # 사용자 설정 환경변수 (관계 리포지토리 환경변수 등)
     ├─ SERVICE-POLICY.md / TECH-STACK.md / ARCHITECTURE.md   # 제품 관통 문서 — 정적 (project-init 작성)
     ├─ DATA-MODEL.md / API-SPEC.md / FEATURES.md / UX-UI.md  # 제품 관통 문서 — 성장 (골격 → plan·task가 채움)
     ├─ rules/
+    │   ├─ TASKERY_RULE.md                # taskery 사용 설명서 (세션 필독)
     │   ├─ TASK_DOC_RULE.md               # task 문서 작성 규칙
     │   ├─ GIT_RULE.md                    # 로컬 깃 운영 규칙
     │   ├─ CHANGELOG_RULE.md              # CHANGELOG 작성 규칙
     │   ├─ MOCKUP_RULE.md                 # UX/UI HTML 목업 규칙
-    │   ├─ DEV_RULE.local.md              # (선택) 이 프로젝트의 구현·테스트 실행 방식
-    │   ├─ TEST_RULE.local.md             # (선택) 이 프로젝트의 검증 범위·방식
+    │   ├─ DEV_RULE.local.md              # 이 프로젝트의 구현 정책 (모든 리포 필수)
+    │   ├─ TEST_RULE.local.md             # 이 프로젝트의 검증 실행 경로·범위 (모든 리포 필수)
     │   └─ *.local.md                     # 사용자 오버라이드 규칙 (패키지 업데이트 대상 제외)
     ├─ plans/                             # plan(기능 그룹)별 PLAN.md / ROADMAP.md (<NNN_slug>/)
     ├─ tasks/                             # task 문서 (<NNN_slug>/BACKLOG.md / spec-diffs / screenshots / mockup 포함)
@@ -138,17 +139,18 @@ my-app/
     ├─ shared/                            # 관계 리포지토리 소통 메세지함
     │   ├─ sent/completed/
     │   └─ received/completed/
-    ├─ FRICTION_LOG.md                    # taskery 불편사항 누적 로그
-    └─ TEST-GUIDE.md                      # 검증 방법 (방식별 이 프로젝트 실행 경로 — /task-plan이 채움)
+    └─ FRICTION_LOG.md                    # taskery 불편사항 누적 로그 (/log-friction 첫 기록 시 생성)
 ```
 
 `.project/`는 플랫폼 무관 공통 자산이다. 진입 문서와 에이전트 자산 위치는 선택한 플랫폼에 따라 갈린다.
 
 | 플랫폼 | 진입 문서 | 스킬 위치 | hook 위치 | hook 등록 |
 |--------|----------|----------|----------|----------|
-| Claude Code | `CLAUDE.md` | `.claude/skills/` | `.claude/hooks/` | `.claude/settings.json` |
+| Claude Code | `CLAUDE.md` (→ `AGENTS.md` 임포트) | `.claude/skills/` | `.claude/hooks/` | `.claude/settings.json` |
 | Codex | `AGENTS.md` | `.agents/skills/` | `.codex/hooks/` | `.codex/config.toml` |
 
+진입 문서 본문은 `AGENTS.md` 한 벌이다. Claude Code는 `AGENTS.md`를 자동으로 읽지 않으므로 `CLAUDE.md`가 이를 임포트한다.
+
 > 스킬 9종과 `git-guard.sh`는 양 플랫폼 동일 자산이다. 진입 문서, hook 등록 방식, 완료 보호 hook(`closed-immutable.sh`)의 구현만 플랫폼별로 다르다. `init`에서 둘 다 선택하면 폴더가 갈려 충돌 없이 공존한다.
 
 ---
@@ -207,7 +209,7 @@ my-app/
 
 | 스킬 | 생성 위치 | 생성 문서 |
 |------|---------|---------|
-| `/project-init` | `.project/` | PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / GLOSSARY.md / .env + 제품 관통 문서(SERVICE-POLICY / TECH-STACK / ARCHITECTURE 작성, DATA-MODEL / API-SPEC / FEATURES / UX-UI 골격 — 타입 해당분) |
+| `/project-init` | `.project/` | PROJECT.md / LINKED-REPOS.md / GLOSSARY.md / .env + 제품 관통 문서(SERVICE-POLICY / TECH-STACK / ARCHITECTURE 작성, DATA-MODEL / API-SPEC / FEATURES / UX-UI 골격 — 타입 해당분) + 리포 로컬 룰 초안(TEST_RULE.local.md / DEV_RULE.local.md) |
 | `/plan-init` | `.project/plans/<NNN_slug>/` | PLAN.md / ROADMAP.md + 제품 관통 문서 FEATURES/UX-UI에 기능 그룹 의도 추가 (제품 관통 문서 전체를 한꺼번에 만들지는 않음) |
 | `/task-init` | `.project/tasks/<NNN_slug>/` | `<NNN>_<slug>.md` (단일 파일) 또는 `TASK-<NNN>_<slug>/task.md` (사용자 명시 시 폴더 승격) |
 
@@ -236,7 +238,7 @@ cd <project-name>
 npx @angar2/taskery init
 ```
 
-이후 메인 세션에 진입(진입 문서 `CLAUDE.md` 또는 `AGENTS.md` 자동 정독)하여 다음 시퀀스로 호출한다. task 5 스킬은 호출과 동시에 상태를 전이시킨다.
+이후 메인 세션에 진입(진입 문서 자동 정독 — 사용법 전체는 `.project/rules/TASKERY_RULE.md`)하여 다음 시퀀스로 호출한다. task 5 스킬은 호출과 동시에 상태를 전이시킨다.
 
 ```
 /project-init                  # 진입 메타 문서와 디렉토리 골격 생성

package/bin/init.js

@@ -31,6 +31,8 @@ const {
   gitignorePatternsFor,
 } = require('./lib');
 
+const { ENTRY_DOCS_MARKER } = require('./migrate');
+
 async function confirm(msg) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -125,6 +127,8 @@ async function main() {
     platforms,
     stale_days: DEFAULT_STALE_DAYS,
     lock_timeout_ms: DEFAULT_LOCK_TIMEOUT_MS,
+    activePlan: null, // /plan-init이 채운다 (0.7.0+ 활성 plan SSoT)
+    entryDocs: ENTRY_DOCS_MARKER, // 신규 설치는 이미 새 진입 문서 체계 — update가 이행을 시도하지 않도록
     files: manifestFiles,
   };
   writeManifest(manifest, manifestPath);
@@ -189,10 +193,11 @@ async function main() {
   console.log(`   카피: ${copied}개 / 스킵: ${skipped}개`);
   console.log(`   플랫폼: ${platforms.join(', ')}`);
   console.log(`   manifest: ${MANIFEST_NAME}\n`);
-  const entryFile = platforms.includes('claude') ? 'CLAUDE.md' : 'AGENTS.md';
   console.log(`다음 단계:`);
   let step = 1;
-  console.log(`  ${step++}. ${entryFile} 정독 + 프로젝트 메타 + 검증 명령 채우기`);
+  // 진입 문서 본문은 AGENTS.md 한 벌 — CLAUDE.md는 `@AGENTS.md` 임포트 한 줄이라 채울 것이 없다.
+  console.log(`  ${step++}. AGENTS.md 정독 + 프로젝트 메타 + 검증/테스트 명령 채우기`);
+  console.log(`     (.project/rules/TASKERY_RULE.md = taskery 사용 설명서 — 세션이 필독)`);
   if (platforms.includes('claude')) {
     console.log(`  ${step++}. Claude 첫 세션에서 taskery MCP 서버 승인 (.mcp.json — 구조화 도구 8종; 미승인 시 npx CLI 폴백)`);
   }

package/bin/lib.js

@@ -22,6 +22,7 @@
  *   - 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 락 안에서 부모(현재 브랜치) 캡처+채번+워크트리·브랜치 생성 원자 실행
@@ -29,7 +30,8 @@
  *   - assertMainWorktreeOn(mainWtPath, branch): 메인 워크트리가 지정 브랜치 체크아웃 상태인지 검증
  *
  * 백로그 (0.1.2+):
- *   - getActiveVersion(mainWtPath): .project/AGENT-GUIDE.md에서 활성 plan 식별자(버전 또는 기능 그룹명) 추출
+ *   - 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 치환 우선)
@@ -63,8 +65,10 @@ const SHARED_DEST = {
 function platformOf(relPath) {
   if (relPath.startsWith('shared/')) return 'shared'; // 공통 — 설치 시 플랫폼별 매핑
   if (relPath === 'CLAUDE.md' || relPath.startsWith('.claude/')) return 'claude';
-  if (relPath === 'AGENTS.md' || relPath.startsWith('.codex/')) return 'codex';
-  return 'agnostic'; // .project/, .gitignore 등 — 항상 설치
+  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/ 상대경로를 특정 플랫폼의 설치 경로로 변환.
@@ -104,9 +108,9 @@ function resolveInstallPlan(templateFiles, platforms, { includeAgnostic = true }
 
 // .gitignore 등록 패턴 (플랫폼별)
 const GITIGNORE_PATTERNS = {
-  agnostic: ['.project/', '.taskery-manifest.json'],
+  agnostic: ['.project/', '.taskery-manifest.json', 'AGENTS.md'],
   claude: ['.claude/', 'CLAUDE.md'],
-  codex: ['.codex/', '.agents/', 'AGENTS.md'],
+  codex: ['.codex/', '.agents/'],
 };
 
 // 선택 플랫폼 + agnostic의 gitignore 패턴 합성 (중복 제거)
@@ -308,6 +312,27 @@ async function withMetaLock(filePath, fn, opts = {}) {
   }
 }
 
+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 currentBranch(mainWtPath) {
   // 메인 워크트리의 현재 브랜치 = 태스크의 부모 브랜치(0.6.0). detached HEAD면 'HEAD' 반환.
   return gitCapture(mainWtPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
@@ -436,31 +461,51 @@ function computeNextPlanNumber(mainWtPath) {
 const BACKLOG_PLACEHOLDER =
   '(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)';
 
-function getActiveVersion(mainWtPath) {
-  // .project/AGENT-GUIDE.md '## 활성 plan 버전' 섹션 다음 비어 있지 않은 첫 줄에서 활성 plan 식별자 추출.
-  // plan = 기능 그룹 단위 → 식별자는 vX.X 버전명 또는 기능 그룹 slug(compare-products 등) 모두 가능.
-  // 헤딩 줄 끝 부가 텍스트(HTML 주석 등) 허용 — project-init 골격이 헤딩에 주석을 달므로
-  // 접두 일치로 판정(_setActivePlan의 findIndex 기준과 동일). 완전 일치 요구 시
-  // 자기 골격을 자기가 못 읽는 자기모순 (recordion FRICTION 2026-08-06, scaffoldError 6회).
+// 구형(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)) {
-    throw new Error(`.project/AGENT-GUIDE.md 부재. /project-init 먼저 호출.`);
-  }
-  const content = fs.readFileSync(guidePath, 'utf8');
-  const sec = content.match(/^##\s*활성 plan 버전[^\n]*\n+([^\n]+)/m);
-  if (!sec) {
-    throw new Error(`.project/AGENT-GUIDE.md '## 활성 plan 버전' 섹션 부재.`);
-  }
+  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('<')) {
-    throw new Error(
-      `'## 활성 plan 버전' 값 미설정(${firstLine || '빈 줄'}) — /plan-init으로 활성 plan 갱신 필요.`,
-    );
-  }
+  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 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만 활성으로 지정 가능.`);
+  }
+  _setActivePlan(mainWtPath, plan);
+  return { plan, planDir };
+}
+
 function getBacklogPath(mainWtPath, activeVersion) {
   const v = activeVersion ?? getActiveVersion(mainWtPath);
   return path.join(mainWtPath, '.project', 'tasks', v, 'BACKLOG.md');
@@ -817,7 +862,7 @@ function _renderTaskSkeleton({ taskNum, title, created, plan, docType, size, par
 
 function scaffoldTaskDoc(mainWtPath, wtPath, meta) {
   // meta: { taskNum, slug, title, type(브랜치 타입), size, parent, plan?, promoted?, created? }
-  // 위치: 등록(.gitignore) 케이스 → 메인WT, 미등록 → 워크트리. plan 미지정 시 AGENT-GUIDE에서 검출.
+  // 위치: 등록(.gitignore) 케이스 → 메인WT, 미등록 → 워크트리. plan 미지정 시 활성 plan(manifest.activePlan)에서 검출.
   // parent 미지정 시 현재 브랜치 캡처(단독 호출 안전망 — 통상 fork가 넘김).
   // taskNum이 고유(fork init 락 채번)라 동일 문서 동시 쓰기 경합 없음 → 락 불요.
   const registered = isProjectRegistered(mainWtPath);
@@ -851,7 +896,7 @@ function scaffoldTaskDoc(mainWtPath, wtPath, meta) {
 }
 
 // ─── plan 생성 (코드화, C3) ─────────────────────────────────────────
-// 채번 + legacy 게이트 + 폴더 mkdir + ROADMAP/PLAN/BACKLOG 골격 + AGENT-GUIDE 활성 plan 갱신을 코드로.
+// 채번 + legacy 게이트 + 폴더 mkdir + ROADMAP/PLAN/BACKLOG 골격 + manifest.activePlan 갱신을 코드로.
 // LLM 몫(FEATURES/UX-UI delta · ROADMAP Stage 내용 · PLAN 링크)은 골격의 placeholder로 남긴다.
 
 function _renderRoadmap(plan) {
@@ -906,29 +951,23 @@ function _renderPlanBacklog(plan) {
 }
 
 function _setActivePlan(mainWtPath, plan) {
-  // AGENT-GUIDE.md '## 활성 plan 버전' 섹션 다음 비어있지 않은 첫 줄을 plan 값으로 교체(헤딩 텍스트 불변).
-  const guidePath = path.join(mainWtPath, '.project', 'AGENT-GUIDE.md');
-  if (!fs.existsSync(guidePath)) {
-    throw new Error('.project/AGENT-GUIDE.md 부재. /project-init 먼저 호출.');
-  }
-  const lines = fs.readFileSync(guidePath, 'utf8').split('\n');
-  const hIdx = lines.findIndex((l) => /^##\s*활성 plan 버전/.test(l));
-  if (hIdx === -1) {
-    throw new Error("AGENT-GUIDE.md '## 활성 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' 먼저 실행.`);
   }
-  const valueLine = `${plan} — \`.project/plans/${plan}/\` 참조`;
-  let i = hIdx + 1;
-  while (i < lines.length && lines[i].trim() === '') i++;
-  if (i < lines.length && !/^#/.test(lines[i])) {
-    lines[i] = valueLine; // 기존 값 줄 교체
-  } else {
-    lines.splice(hIdx + 1, 0, '', valueLine); // 값 줄 부재 → 헤딩 뒤 삽입
-  }
-  fs.writeFileSync(guidePath, lines.join('\n'));
+  withMetaLockSync(manifestPath, () => {
+    const manifest = readManifest(manifestPath);
+    if (!manifest) throw new Error(`${MANIFEST_NAME} 읽기 실패.`);
+    manifest.activePlan = plan;
+    writeManifest(manifest, manifestPath);
+  });
 }
 
 function initPlan(mainWtPath, slug, opts = {}) {
-  // 채번 → legacy 게이트 → 폴더 + 골격 + AGENT-GUIDE 갱신. slug 검증은 CLI 측.
+  // 채번 → legacy 게이트 → 폴더 + 골격 + manifest.activePlan 갱신. slug 검증은 CLI 측.
   // legacy 폴더(NNN_ 아닌 plan 폴더) 잔존 + !force → { gated:true } 반환(CLI가 사용자 confirm 후 force 재호출).
   const { next, legacyDirs } = computeNextPlanNumber(mainWtPath);
   if (legacyDirs.length && !opts.force) {
@@ -1258,6 +1297,7 @@ module.exports = {
   getInitLockPath,
   withMergeLock,
   withMetaLock,
+  withMetaLockSync,
   currentBranch,
   assertMainWorktreeOn,
   parseBranchName,
@@ -1268,6 +1308,7 @@ module.exports = {
   // 백로그 (0.1.2+)
   BACKLOG_PLACEHOLDER,
   getActiveVersion,
+  setActivePlan,
   getBacklogPath,
   computeNextBLNumber,
   formatBacklogBlock,

package/bin/mcp.js

@@ -7,7 +7,7 @@
  * 도구 8종 = CLI 명령과 동일한 lib.js 함수의 다른 입구(네이티브 구조화 인자/반환).
  *   backlog_add / backlog_get / backlog_mark — 활성 plan BACKLOG.md 조작
  *   set_status   — task 헤더 상태 전이 (7×7 유효전이 검증, closed 거부)
- *   plan_init    — plan 생성 (채번+골격+AGENT-GUIDE 갱신)
+ *   plan_init    — plan 생성 (채번+골격+manifest.activePlan 갱신)
  *   task_init    — task 분기 (fork 원자 채번 + §1.3 골격 자동 생성)
  *   task_close   — close 결정적 준비만 (Phase커밋·status=closed·마커). 비가역 머지/정리는 스킬.
  *   status       — 멀티세션 현황 + 활성 plan
@@ -159,7 +159,7 @@ server.registerTool(
   'plan_init',
   {
     description:
-      'plan(기능 그룹) 생성 — 채번 + 폴더 + ROADMAP/PLAN/BACKLOG 골격 + AGENT-GUIDE 활성plan 갱신. 이후 골격 내용은 LLM이 채움. legacy 폴더 잔존 시 gated 반환(force로 재호출).',
+      'plan(기능 그룹) 생성 — 채번 + 폴더 + ROADMAP/PLAN/BACKLOG 골격 + 활성 plan 갱신. 이후 골격 내용은 LLM이 채움. legacy 폴더 잔존 시 gated 반환(force로 재호출).',
     inputSchema: {
       slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
       force: z.boolean().optional().describe('legacy 게이트 무시'),

package/bin/migrate.js

@@ -0,0 +1,306 @@
+// 0.7.0 문서 체계 재편 마이그레이션 — update가 기존 설치본을 새 구조로 이행시킨다
+/**
+ * bin/migrate.js
+ * `npx @angar2/taskery update`가 호출하는 0.7.0 이행 로직 모음.
+ *
+ * 이행 4종:
+ *   1. ingestActivePlan  — 구형 AGENT-GUIDE.md '## 활성 plan 버전' → manifest.activePlan (1회)
+ *   2. migrateEntryDocs  — 진입 문서 재편. 기존 CLAUDE.md/AGENTS.md의 *리포 값* 4섹션을 추출해
+ *                          새 AGENTS.md에 주입하고, CLAUDE.md는 `@AGENTS.md` 한 줄로 축약.
+ *                          **update 본 루프보다 먼저 실행하고, 처리한 경로를 본 루프에서 제외한다.**
+ *                          본 루프에 맡기면 '사용자 customize 검출' 프롬프트가 뜨는데,
+ *                          덮으면 리포 값이 .bak에만 남고 안 덮으면 구판 전문이 남아 새 판과 충돌한다.
+ *   3. migrateGitignore  — AGENTS.md가 agnostic으로 바뀌어 모든 리포에 새로 깔리는데
+ *                          .gitignore 기록은 init에만 있어 누락된다. 누락 패턴 append 제안.
+ *   4. migrateTestGuide  — 폐지되는 TEST-GUIDE.md의 축적 내용을 TEST_RULE.local.md로 1회 이관.
+ *
+ * 원칙: 사용자 값은 절대 유실시키지 않는다. 추출 실패 시 어느 파일도 덮지 않고 `.new`로 보류한다.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { sha256, copyFile, gitignorePatternsFor } = require('./lib');
+
+// 진입 문서에서 이식할 *리포 값* 섹션. 헤딩 텍스트 접두로 매칭한다 —
+// 실제 문서의 헤딩은 '## 검수 실행 명령 (해당 시 — 앱 실행·검수가 필요한 프로젝트)'처럼
+// 뒤에 부가 텍스트가 붙는다. 완전 일치를 요구하면 못 찾는다.
+const REPO_VALUE_SECTIONS = ['프로젝트 메타', '검증 명령', '테스트 명령', '검수 실행 명령'];
+// 이 중 없어도 이행을 계속하는 항목 — 앱 검수가 없는 프로젝트는 이 절을 지웠을 수 있다.
+const OPTIONAL_SECTIONS = new Set(['검수 실행 명령']);
+// 진입 문서 이행 완료 마커 — manifest에 기록해 재실행을 막는다.
+const ENTRY_DOCS_MARKER = '0.7.0';
+
+function isBefore070(version) {
+  if (typeof version !== 'string') return true;
+  const [maj = 0, min = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
+  return maj < 1 && min < 7;
+}
+
+// 마크다운을 '## ' 헤딩 단위로 쪼개 { key, heading, body } 목록으로 만든다.
+// 코드펜스 내부는 헤딩으로 보지 않는다 — 셸 주석(`## ...`)이 든 예시 블록을 헤딩으로 오인하면
+// 그 뒤 본문이 조용히 잘려 사용자 값이 유실된다(경고도 안 뜬다).
+function splitSections(content) {
+  const lines = content.split('\n');
+  const out = [];
+  let cur = null;
+  let inFence = false;
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    const m = inFence ? null : line.match(/^##\s+(.*)$/);
+    if (m) {
+      if (cur) out.push(cur);
+      cur = { heading: line, title: m[1].trim(), body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+function findSectionBody(sections, key) {
+  const hit = sections.find((s) => s.title.startsWith(key));
+  if (!hit) return null;
+  // 뒤쪽 빈 줄과 구분선(---)은 새 템플릿 쪽 서식을 쓰므로 떼어낸다.
+  const body = hit.body.slice();
+  while (body.length && (body[body.length - 1].trim() === '' || body[body.length - 1].trim() === '---')) {
+    body.pop();
+  }
+  while (body.length && body[0].trim() === '') body.shift();
+  return body.join('\n');
+}
+
+// 새 AGENTS.md 템플릿의 해당 섹션 본문을 추출한 값으로 갈아끼운다.
+function injectSections(templateContent, extracted) {
+  const lines = templateContent.split('\n');
+  const heads = new Set();
+  let fence = false;
+  lines.forEach((l, idx) => {
+    if (/^\s*(```|~~~)/.test(l)) fence = !fence;
+    else if (!fence && /^##\s+/.test(l)) heads.add(idx);
+  });
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const m = heads.has(i) ? lines[i].match(/^##\s+(.*)$/) : null;
+    const key = m && REPO_VALUE_SECTIONS.find((k) => m[1].trim().startsWith(k));
+    if (!key || extracted[key] == null) {
+      out.push(lines[i]);
+      i++;
+      continue;
+    }
+    out.push(lines[i]); // 헤딩은 새 템플릿 것을 유지
+    i++;
+    // 기존 본문(다음 '## ' 직전까지)을 건너뛰면서, 끝의 빈 줄/구분선은 보존한다.
+    const skipped = [];
+    while (i < lines.length && !heads.has(i)) {
+      skipped.push(lines[i]);
+      i++;
+    }
+    const tail = [];
+    while (skipped.length && (skipped[skipped.length - 1].trim() === '' || skipped[skipped.length - 1].trim() === '---')) {
+      tail.unshift(skipped.pop());
+    }
+    out.push('', extracted[key], ...tail);
+  }
+  return out.join('\n');
+}
+
+/**
+ * 1. 활성 plan 이식 — manifest.activePlan이 이미 있으면 그것을 그대로 보존한다.
+ *    (update가 manifest를 새로 조립하므로 보존을 명시하지 않으면 매번 증발한다.)
+ */
+function ingestActivePlan(cwd, oldManifest) {
+  if (oldManifest.activePlan) return { activePlan: oldManifest.activePlan, ingested: false };
+  const guidePath = path.join(cwd, '.project', 'AGENT-GUIDE.md');
+  if (!fs.existsSync(guidePath)) return { activePlan: null, ingested: false };
+  const sec = fs.readFileSync(guidePath, 'utf8').match(/^##\s*활성 plan 버전[^\n]*\n+([^\n]+)/m);
+  if (!sec) return { activePlan: null, ingested: false };
+  const firstLine = sec[1].trim();
+  if (!firstLine || firstLine.startsWith('<')) return { activePlan: null, ingested: false };
+  return { activePlan: firstLine.split(/\s+/)[0], ingested: true };
+}
+
+/**
+ * 2. 진입 문서 재편.
+ * @returns {{ handled: string[], entries: object, notes: string[], held: boolean }}
+ *   handled — update 본 루프에서 제외할 설치 경로
+ *   entries — manifest.files에 기록할 항목 (설치 경로 → { hash, core, managed })
+ */
+function migrateEntryDocs(cwd, templateDir, platforms, oldManifest) {
+  const notes = [];
+  const entries = {};
+  const skip = { handled: [], entries, notes, held: false, done: false };
+
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  const claudePath = path.join(cwd, 'CLAUDE.md');
+  const hasAgents = fs.existsSync(agentsPath);
+  const hasClaude = fs.existsSync(claudePath);
+  if (!hasAgents && !hasClaude) return skip;
+
+  // 이미 이행된 리포는 건너뛴다. 판정은 manifest 마커(ENTRY_DOCS_MARKER) 하나로만 한다.
+  //  - 파일 구조로 추정하면 플랫폼별로 오판한다: codex 단독은 CLAUDE.md가 없어 "이행됨"으로 읽혀
+  //    구판 AGENTS.md가 본 루프의 customize 프롬프트로 넘어가고 리포 값이 .bak에만 남았다.
+  //  - 버전으로도 거르지 않는다: update는 이행이 보류(held)돼도 manifest 버전을 올리므로
+  //    버전 게이트를 두면 보류된 리포가 영영 재시도되지 않는다("다음 update가 다시 시도합니다"가 거짓이 된다).
+  //  - 신규 설치는 init이 마커를 박아 두므로 이 한 줄로 걸러진다.
+  if (oldManifest.entryDocs === ENTRY_DOCS_MARKER) return skip;
+
+  // 소스 선정: AGENTS.md 우선(양쪽은 미러라 값이 같다), 없으면 CLAUDE.md.
+  const srcPath = hasAgents ? agentsPath : claudePath;
+  const srcName = hasAgents ? 'AGENTS.md' : 'CLAUDE.md';
+  const sections = splitSections(fs.readFileSync(srcPath, 'utf8'));
+
+  const extracted = {};
+  const missing = [];
+  for (const key of REPO_VALUE_SECTIONS) {
+    const body = findSectionBody(sections, key);
+    if (body == null) missing.push(key);
+    else extracted[key] = body;
+  }
+  const fatalMissing = missing.filter((k) => !OPTIONAL_SECTIONS.has(k));
+
+  const newAgentsSrc = path.join(templateDir, 'AGENTS.md');
+  const newAgents = fs.readFileSync(newAgentsSrc, 'utf8');
+
+  if (fatalMissing.length > 0) {
+    // 값 유실 방지 — 어느 파일도 덮지 않고 새 판을 .new로 남긴다. manifest도 갱신하지 않아
+    // 다음 update가 다시 시도한다.
+    fs.writeFileSync(path.join(cwd, 'AGENTS.md.new'), newAgents);
+    notes.push(
+      `⚠ 진입 문서 이행 보류 — ${srcName}에서 필수 섹션을 찾지 못함 (${fatalMissing.join(', ')}).`,
+      `   새 판을 AGENTS.md.new 로 두었습니다. 리포 값을 직접 옮긴 후 AGENTS.md 로 바꿔주세요.`,
+      `   (기존 파일은 그대로 보존되었고 manifest도 갱신하지 않아 다음 update가 다시 시도합니다.)`,
+    );
+    return { handled: ['AGENTS.md', 'CLAUDE.md'], entries, notes, held: true, done: false };
+  }
+
+  // AGENTS.md 생성 — 새 템플릿에 리포 값 주입.
+  // .bak은 *최초 1회만* 남긴다 — 이미 있으면 그게 사용자의 원본이다. 덮으면 원본이 사라진다.
+  if (fs.existsSync(agentsPath) && !fs.existsSync(agentsPath + '.bak')) {
+    fs.copyFileSync(agentsPath, agentsPath + '.bak');
+  }
+  fs.writeFileSync(agentsPath, injectSections(newAgents, extracted));
+  entries['AGENTS.md'] = { hash: sha256(newAgentsSrc), core: true, managed: true };
+
+  const injectedCount = REPO_VALUE_SECTIONS.length - missing.length;
+  notes.push(`진입 문서 재편 — ${srcName}에서 리포 값 ${injectedCount}개 섹션을 AGENTS.md로 이식.`);
+  if (missing.length > 0) {
+    notes.push(`   (없어서 새 템플릿 기본값으로 둔 절: ${missing.join(', ')})`);
+  }
+
+  const handled = ['AGENTS.md'];
+
+  // CLAUDE.md는 `@AGENTS.md` 한 줄로 축약 (claude 플랫폼일 때만).
+  if (platforms.includes('claude')) {
+    const claudeSrc = path.join(templateDir, 'CLAUDE.md');
+    if (hasClaude && !fs.existsSync(claudePath + '.bak')) {
+      fs.copyFileSync(claudePath, claudePath + '.bak');
+      notes.push(`   기존 CLAUDE.md는 CLAUDE.md.bak 으로 백업.`);
+    }
+    copyFile(claudeSrc, claudePath);
+    entries['CLAUDE.md'] = { hash: sha256(claudeSrc), core: true, managed: true };
+    handled.push('CLAUDE.md');
+    notes.push(`   CLAUDE.md는 '@AGENTS.md' 임포트 한 줄로 축약.`);
+  }
+
+  return { handled, entries, notes, held: false, done: true };
+}
+
+/**
+ * 3. .gitignore 누락 패턴 — 이미 taskery 패턴을 쓰는 리포에만 제안한다.
+ *    (init에서 등록을 거부한 리포는 패턴이 하나도 없으므로 건드리지 않는다.)
+ * @returns {{ missing: string[], apply: function }} — missing이 비면 제안 불필요
+ */
+function planGitignore(cwd, platforms) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) return { missing: [] };
+  const wanted = gitignorePatternsFor(platforms);
+  const existing = new Set(
+    fs.readFileSync(gitignorePath, 'utf8').split('\n').map((l) => l.trim()),
+  );
+  const already = wanted.filter((p) => existing.has(p));
+  if (already.length === 0) return { missing: [] }; // taskery 패턴 미사용 리포 — 선택 존중
+  const missing = wanted.filter((p) => !existing.has(p));
+  return {
+    missing,
+    apply() {
+      fs.appendFileSync(gitignorePath, `\n${missing.join('\n')}\n`);
+    },
+  };
+}
+
+/**
+ * 4. TEST-GUIDE.md → TEST_RULE.local.md 이관.
+ *    폐지되는 문서라 그대로 두면 새 참조처들이 읽지 않아 축적 내용이 고아가 된다.
+ *    원본은 지우지 않는다(사용자 파일 불가침).
+ * @returns {{ available: boolean, apply: function }}
+ */
+function planTestGuide(cwd) {
+  const guidePath = path.join(cwd, '.project', 'TEST-GUIDE.md');
+  const localPath = path.join(cwd, '.project', 'rules', 'TEST_RULE.local.md');
+  if (!fs.existsSync(guidePath)) return { available: false };
+  if (fs.existsSync(localPath)) {
+    // 둘 다 있으면 자동 병합하지 않는다(사용자 파일 훼손 위험). 다만 침묵하면
+    // TEST-GUIDE에 쌓인 내용이 아무도 안 읽는 채로 남으므로 반드시 알린다.
+    return { available: false, conflict: true };
+  }
+  return {
+    available: true,
+    apply() {
+      const body = fs.readFileSync(guidePath, 'utf8');
+      // 머리말만 새 역할에 맞게 갈아끼우고 본문(축적된 실행 경로)은 그대로 옮긴다.
+      const stripped = body.replace(/^#\s*TEST-GUIDE[^\n]*\n(>[^\n]*\n)*/, '');
+      const header = [
+        '# TEST_RULE.local.md — 이 리포의 검증 규칙',
+        '',
+        '> 이 프로젝트에서 각 테스트 방식을 *실제로 어떻게 실행하나* + *무엇을 얼마나 검증하나*의 단일 소스.',
+        '> `.project/TEST-GUIDE.md`(0.7.0에서 폐지)의 내용을 이관한 문서다. 구성과 의무는 `TASKERY_RULE` §8 참조.',
+        '> `*.local.md`는 taskery update가 건드리지 않는다 — 이 리포가 소유한다.',
+        '',
+      ].join('\n');
+      fs.mkdirSync(path.dirname(localPath), { recursive: true });
+      fs.writeFileSync(localPath, header + stripped);
+    },
+  };
+}
+
+/**
+ * 5. `.gitignore` 병합 — **덮어쓰기 금지.**
+ *    template/.gitignore는 manifest 관리 자산이라 update의 '신규' 분기가 그대로 복사해버리는데,
+ *    실사용 리포는 대부분 .gitignore를 manifest에 안 들고 있다(init 이전부터 있던 파일).
+ *    그대로 두면 사용자의 node_modules·빌드 산출물·프로젝트 고유 무시 규칙이 통째로 사라진다.
+ *    → 없으면 복사, 있으면 *빠진 줄만 덧붙인다*. 기존 줄은 절대 건드리지 않는다.
+ * @returns {{ merged: boolean, added: string[] }}
+ */
+function mergeGitignore(srcPath, dstPath) {
+  if (!fs.existsSync(dstPath)) {
+    copyFile(srcPath, dstPath);
+    return { merged: false, added: [] };
+  }
+  const cur = fs.readFileSync(dstPath, 'utf8');
+  const have = new Set(cur.split('\n').map((l) => l.trim()));
+  const added = fs
+    .readFileSync(srcPath, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#') && !have.has(l));
+  if (added.length === 0) return { merged: true, added: [] };
+  const lead = cur.endsWith('\n') ? '' : '\n';
+  fs.appendFileSync(dstPath, `${lead}\n# taskery 템플릿 추가분\n${added.join('\n')}\n`);
+  return { merged: true, added };
+}
+
+module.exports = {
+  ENTRY_DOCS_MARKER,
+  mergeGitignore,
+  isBefore070,
+  splitSections,
+  findSectionBody,
+  injectSections,
+  ingestActivePlan,
+  migrateEntryDocs,
+  planGitignore,
+  planTestGuide,
+};