@angar2/taskery 0.6.1 → 0.8.0

package/bin/migrate.js

@@ -0,0 +1,344 @@
+// 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`);
+    },
+  };
+}
+
+// TEST_RULE.local.md 필수 절 골격(TASKERY_RULE §8) — 이관 본문에 없으면 append한다.
+// 문안은 project-init 골격과 동일 유지. '방식별 실행 경로'는 이관 본문 자체가 그 내용이라 제외.
+const TEST_RULE_REQUIRED_SECTIONS = [
+  {
+    key: '테스트 실행 환경',
+    block: [
+      '## 테스트 실행 환경 (격리 실행 경로)',
+      '',
+      '> 실제 앱을 띄워 UI를 자동 조작하는 스위트를 **사용자의 화면·마우스·키보드를 뺏지 않고** 돌리는 경로.',
+      '> 여기가 비어 있으면 자동 게이트·격리 세션은 그 스위트를 실행하지 않고 사용자 승인을 받는다.',
+      '> 적을 수 있는 것: 창 숨김·헤드리스 플래그 / 가상 디스플레이·컨테이너 / VM / CI 러너 위임 / 점유 스위트를 제외하는 한정 실행 옵션.',
+      '> 결정 자체도 기록 대상 — 격리 경로를 두지 않기로 했다면 *"없음 — 매번 승인(사용자 결정 YYYY-MM-DD)"*로 적어 미결정 상태와 구분한다.',
+      '',
+      '<아직 미정 — 여기에 이 리포의 격리 실행 경로를 채운다>',
+    ].join('\n'),
+  },
+  {
+    key: '범위·방식 정책',
+    block: [
+      '## 범위·방식 정책',
+      '',
+      '> 무엇을 얼마나 검증하나 — 수정 루프에서의 실행 범위, 테스트 신설 상한 등.',
+      '',
+      '<아직 미정 — 여기에 이 리포의 범위 정책을 채운다>',
+    ].join('\n'),
+  },
+];
+
+/**
+ * 4. TEST-GUIDE.md → TEST_RULE.local.md 이관.
+ *    폐지되는 문서라 그대로 두면 새 참조처들이 읽지 않아 축적 내용이 고아가 된다.
+ *    원본은 지우지 않는다(사용자 파일 불가침).
+ * @returns {{ available: boolean, apply: function }} — apply()는 append한 필수 절 key 목록을 반환
+ */
+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');
+      // 필수 절 골격 보강 — TEST-GUIDE에는 없던 절(TASKERY_RULE §8)이라 이관만으로는 빠진다.
+      // 헤딩은 접두 일치로 검사한다(완전 일치 요구 금지 — 뒤에 부가 텍스트가 붙는다).
+      const titles = splitSections(stripped).map((s) => s.title);
+      const appended = TEST_RULE_REQUIRED_SECTIONS.filter(
+        (sec) => !titles.some((t) => t.startsWith(sec.key)),
+      );
+      const tail = appended.length
+        ? `${stripped.endsWith('\n') ? '' : '\n'}\n${appended.map((s) => s.block).join('\n\n')}\n`
+        : '';
+      fs.mkdirSync(path.dirname(localPath), { recursive: true });
+      fs.writeFileSync(localPath, header + stripped + tail);
+      return appended.map((s) => s.key);
+    },
+  };
+}
+
+/**
+ * 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,
+};

package/bin/plan.js

@@ -1,16 +1,22 @@
 #!/usr/bin/env node
-// plan(기능 그룹) 생성 CLI — 채번+폴더+ROADMAP/PLAN/BACKLOG 골격+AGENT-GUIDE 갱신 원자 실행
+// plan(기능 그룹) 생성·전환 CLI — 채번+폴더+ROADMAP/PLAN/BACKLOG 골격+활성plan 갱신 원자 실행
 /**
  * bin/plan.js
- * `npx @angar2/taskery plan-init <slug> [--force]` — plan 생성.
+ * `npx @angar2/taskery plan-init <slug> [--force]`   — plan 생성.
+ * `npx @angar2/taskery plan-switch <NNN_slug>`       — 활성 plan 전환.
  *
- * 채번(NNN) + legacy 게이트 + 폴더 mkdir(plans/<NNN_slug> + tasks/<NNN_slug>/{spec-diffs,screenshots,mockup})
- * + ROADMAP/PLAN/BACKLOG 골격 Write + AGENT-GUIDE 활성 plan 갱신을 코드가 수행.
- * 성공 시 JSON 한 줄 — { plan, nnn, planDir, tasksDir }. 이후 ROADMAP Stage 내용·PLAN 링크·
- * FEATURES/UX-UI delta는 LLM(plan-init 스킬)이 골격 placeholder를 채운다.
+ * dispatcher가 op('init' | 'switch')를 선행 인자로 주입한다 (backlog.js와 동일 패턴).
  *
- * legacy 폴더(NNN_ 아닌 plan 폴더) 잔존 + --force 없음 → exit 2 + { gated:true, legacyDirs }
- *   (스킬이 사용자 confirm 후 --force로 재호출). 그 외 실패 시 stderr + exit 1.
+ * init: 채번(NNN) + legacy 게이트 + 폴더 mkdir(plans/<NNN_slug> + tasks/<NNN_slug>/{spec-diffs,screenshots,mockup})
+ *   + ROADMAP/PLAN/BACKLOG 골격 Write + manifest.activePlan 갱신을 코드가 수행.
+ *   성공 시 JSON 한 줄 — { plan, nnn, planDir, tasksDir }. 이후 ROADMAP Stage 내용·PLAN 링크·
+ *   FEATURES/UX-UI delta는 LLM(plan-init 스킬)이 골격 placeholder를 채운다.
+ *   legacy 폴더(NNN_ 아닌 plan 폴더) 잔존 + --force 없음 → exit 2 + { gated:true, legacyDirs }
+ *     (스킬이 사용자 confirm 후 --force로 재호출).
+ *
+ * switch: 대상 plan 폴더 실재 검증 후 manifest.activePlan 갱신. 성공 시 JSON — { plan, planDir }.
+ *
+ * 그 외 실패 시 stderr + exit 1.
  */
 
 const path = require('path');
@@ -20,10 +26,25 @@ const {
   readManifest,
   getMainWorktreePath,
   initPlan,
+  setActivePlan,
 } = require('./lib');
 
-function main() {
-  const argv = process.argv.slice(2);
+function resolveMainWt() {
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery plan 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+  return mainWt;
+}
+
+function runInit(argv) {
   const positional = [];
   let force = false;
   for (const a of argv) {
@@ -42,17 +63,7 @@ function main() {
     process.exit(1);
   }
 
-  let mainWt;
-  try {
-    mainWt = getMainWorktreePath();
-  } catch (e) {
-    console.error(`taskery plan-init 실패: ${e.message}`);
-    process.exit(1);
-  }
-  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
-    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
-    process.exit(1);
-  }
+  const mainWt = resolveMainWt();
 
   let result;
   try {
@@ -82,4 +93,33 @@ function main() {
   );
 }
 
+function runSwitch(argv) {
+  const plan = argv.filter((a) => !a.startsWith('--'))[0];
+  if (!plan) {
+    console.error('사용법: npx @angar2/taskery plan-switch <NNN_slug>');
+    console.error('예: npx @angar2/taskery plan-switch 002_compare-products');
+    process.exit(1);
+  }
+
+  const mainWt = resolveMainWt();
+
+  let result;
+  try {
+    result = setActivePlan(mainWt, plan);
+  } catch (e) {
+    console.error(`taskery plan-switch 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify({ plan: result.plan, planDir: result.planDir }) + '\n');
+}
+
+function main() {
+  const [op, ...rest] = process.argv.slice(2);
+  if (op === 'init') return runInit(rest);
+  if (op === 'switch') return runSwitch(rest);
+  console.error(`taskery plan: 알 수 없는 op '${op}' (init | switch)`);
+  process.exit(1);
+}
+
 main();

package/bin/set-status.js

@@ -22,6 +22,9 @@ const {
   resolveTaskDocPath,
   setStatus,
   TRANSITIONS,
+  getActiveTasks,
+  getWorktreePath,
+  getProjectId,
 } = require('./lib');
 
 async function main() {
@@ -60,13 +63,25 @@ async function main() {
     process.exit(1);
   }
 
-  // 현재 작업트리 toplevel = 미등록 케이스의 문서 base (호출 위치 = 해당 워크트리).
+  // 현재 작업트리 toplevel = 미등록 케이스의 문서 base.
   const wtPath = gitCapture(process.cwd(), ['rev-parse', '--show-toplevel'], { allowFail: true }) || mainWt;
 
-  const resolved = resolveTaskDocPath(mainWt, wtPath, { taskNum });
+  let resolved = resolveTaskDocPath(mainWt, wtPath, { taskNum });
+
+  // 미등록 케이스에서 메인 워크트리(또는 다른 task의 워크트리)에서 호출하면 문서가 그 트리에 없다.
+  // 호출 위치를 강요하는 대신 SSoT에서 해당 task의 워크트리를 역조회해 한 번 더 찾는다
+  // — 스킬이 "호출 위치 자유"를 전제하므로 CLI가 그 약속을 지켜야 한다.
+  if (!resolved) {
+    const hit = getActiveTasks(mainWt).find((t) => t.taskNum === taskNum);
+    if (hit) {
+      const owner = getWorktreePath(getProjectId(mainWt), hit);
+      if (owner !== wtPath) resolved = resolveTaskDocPath(mainWt, owner, { taskNum });
+    }
+  }
+
   if (!resolved) {
     console.error(
-      `TASK-${String(taskNum).padStart(3, '0')} 문서를 찾지 못함 (.project/tasks/*/ 아래 단일 파일/폴더 승격 모두 탐색).`,
+      `TASK-${String(taskNum).padStart(3, '0')} 문서를 찾지 못함 (.project/tasks/*/ 아래 단일 파일/폴더 승격 모두 탐색 + 진행중 task 워크트리 역조회).`,
     );
     process.exit(1);
   }

package/bin/status.js

@@ -23,6 +23,7 @@ const {
   gitCapture,
   getMainWorktreePath,
   getActiveTasks,
+  getActiveVersion,
   getWorktreesRoot,
   getMergeLockPath,
   DEFAULT_STALE_DAYS,
@@ -65,6 +66,17 @@ function main() {
     `현재 브랜치(= 새 태스크 부모): ${currentBranch}${detached ? ' ⚠ (detached HEAD — 브랜치 체크아웃 필요)' : ''}`,
   );
   console.log(`projectId: ${projectId}`);
+  // 활성 plan(0.7.0+ manifest SSoT) — 스킬·진입 문서가 "활성 plan은 status로 확인"이라
+  // 지시하므로 여기서 반드시 출력한다. 미설정이면 다음 행동까지 안내한다.
+  let activePlan = null;
+  try {
+    activePlan = getActiveVersion(mainWt);
+  } catch (e) {
+    activePlan = null;
+  }
+  console.log(
+    `활성 plan: ${activePlan ?? '미설정 — /plan-init으로 생성하거나 plan-switch <NNN_slug>로 지정'}`,
+  );
   console.log(`stale_days: ${staleDays} / lock_timeout_ms: ${lockTimeoutMs}\n`);
 
   // 2. 머지 락 상태

package/bin/taskery.js

@@ -12,7 +12,8 @@
  *   fork    — task 분기 (채번+워크트리+브랜치 생성 init 락 원자 실행, 0.3.2+) + 골격 task.md 자동 생성(--size/--title)
  *   backlog-add/get/mark — 활성 plan BACKLOG.md 조작 (채번/조회/확인 마킹, 코드화)
  *   set-status — task 헤더 상태 전이 (7×7 유효전이 검증, 코드화)
- *   plan-init — plan 생성 (채번+폴더+ROADMAP/PLAN/BACKLOG 골격+AGENT-GUIDE 갱신, 코드화)
+ *   plan-init — plan 생성 (채번+폴더+ROADMAP/PLAN/BACKLOG 골격+manifest.activePlan 갱신, 코드화)
+ *   plan-switch — 활성 plan 전환 (manifest.activePlan 갱신, 0.7.0+)
  *   close   — close 결정적 준비 (Phase커밋+status=closed+문서커밋+추적마커; 비가역 머지/정리는 스킬, 코드화)
  *   mcp     — stdio MCP 서버 기동 (lib core를 도구 8종으로 노출; Claude/Codex 등록)
  *   help    — 사용법 출력
@@ -47,6 +48,7 @@ function help() {
   npx @angar2/taskery backlog-mark <BL-NNN> <TASK-NNN> 백로그 확인 마킹
   npx @angar2/taskery set-status <TASK-NNN> <state>    task 상태 전이 (유효전이 검증)
   npx @angar2/taskery plan-init <slug> [--force]       plan 생성 (채번+폴더+골격+활성plan 갱신)
+  npx @angar2/taskery plan-switch <NNN_slug>           활성 plan 전환
   npx @angar2/taskery close <TASK-NNN>                 close 결정적 준비 (Phase커밋+status=closed+추적마커)
   npx @angar2/taskery mcp                              MCP stdio 서버 기동 (Claude .mcp.json / Codex codex mcp add 등록)
   npx @angar2/taskery help      도움말
@@ -105,7 +107,10 @@ switch (sub) {
     runScript('set-status.js');
     break;
   case 'plan-init':
-    runScript('plan.js');
+    runScript('plan.js', ['init']);
+    break;
+  case 'plan-switch':
+    runScript('plan.js', ['switch']);
     break;
   case 'close':
     runScript('close.js');

package/bin/update.js

@@ -38,6 +38,15 @@ const {
   resolveInstallPlan,
 } = require('./lib');
 
+const {
+  ENTRY_DOCS_MARKER,
+  mergeGitignore,
+  ingestActivePlan,
+  migrateEntryDocs,
+  planGitignore,
+  planTestGuide,
+} = require('./migrate');
+
 async function confirm(msg) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -82,8 +91,22 @@ async function main() {
   const newFiles = {};
   const summary = { unchanged: 0, new: 0, autoUpdated: 0, customizedReplaced: 0, skipped: 0, removed: 0 };
 
+  // 2.5. 0.7.0 진입 문서 재편 — **본 루프보다 먼저.**
+  //   CLAUDE.md/AGENTS.md를 본 루프에 맡기면 '사용자 customize 검출' 프롬프트가 뜨는데,
+  //   덮으면 리포 값이 .bak에만 남고 안 덮으면 구판 전문이 새 판과 함께 남아 규칙이 충돌한다.
+  //   이행이 최종 상태까지 기록하고, 처리한 경로는 아래 루프에서 제외한다.
+  const entryMig = migrateEntryDocs(cwd, templateDir, platforms, oldManifest);
+  const entryHandled = new Set(entryMig.handled);
+  for (const line of entryMig.notes) console.log(`  ${line}`);
+  Object.assign(newFiles, entryMig.entries);
+
   // 3. 새 template 파일 분기 (rel = 설치 경로 installRel)
   for (const [rel, { hash: newHash, templateRel }] of Object.entries(newTemplateFiles)) {
+    if (entryHandled.has(rel)) {
+      // 2.5에서 이행 완료(또는 보류) — 본 루프가 다시 손대면 이행 결과를 덮는다.
+      if (entryMig.held && oldFiles[rel]) newFiles[rel] = oldFiles[rel];
+      continue;
+    }
     if (isLocalOverride(rel)) {
       // template에 .local.md 들어가면 안 되지만 방어적 스킵
       console.log(`  skip (.local override 영역): ${rel}`);
@@ -95,6 +118,17 @@ async function main() {
     const dst = path.join(cwd, rel);
     const oldEntry = oldFiles[rel];
 
+    // .gitignore는 *절대 덮어쓰지 않는다* — 사용자 무시 규칙이 통째로 날아간다.
+    // 없으면 복사, 있으면 빠진 줄만 덧붙인다(migrate.mergeGitignore).
+    if (rel === '.gitignore') {
+      const r = mergeGitignore(src, dst);
+      newFiles[rel] = { hash: newHash, core: true, managed: true };
+      if (!r.merged) { summary.new++; console.log(`  new: ${rel}`); }
+      else if (r.added.length) { summary.autoUpdated++; console.log(`  merge: ${rel} — ${r.added.length}줄 추가 (기존 줄 보존)`); }
+      else { summary.unchanged++; }
+      continue;
+    }
+
     // a. 신규 — manifest에 없음
     if (!oldEntry) {
       copyFile(src, dst);
@@ -173,6 +207,12 @@ async function main() {
       : (migration.lock_timeout_ms = true, DEFAULT_LOCK_TIMEOUT_MS);
   if (!Array.isArray(oldManifest.platforms)) migration.platforms = true;
 
+  // 활성 plan(0.7.0+) — 기존 값이 있으면 **반드시 그대로 보존**한다. newManifest는 아래에서
+  // 명시 필드 목록으로 새로 조립되므로, 여기서 넘기지 않으면 update 한 번에 활성 plan이
+  // 소리 없이 사라지고 구형 AGENT-GUIDE 폴백의 낡은 값으로 되돌아간다.
+  const { activePlan, ingested: activePlanIngested } = ingestActivePlan(cwd, oldManifest);
+  if (activePlanIngested) migration.activePlan = true;
+
   const newManifest = {
     version: getPackageVersion(),
     installed_at: oldManifest.installed_at,
@@ -181,10 +221,45 @@ async function main() {
     platforms,
     stale_days,
     lock_timeout_ms,
+    activePlan: activePlan ?? null,
+    // 진입 문서 이행 완료 마커 — 있으면 다음 update가 이행을 재실행하지 않는다.
+    entryDocs: entryMig.done ? ENTRY_DOCS_MARKER : (oldManifest.entryDocs ?? null),
     files: newFiles,
   };
   writeManifest(newManifest, manifestPath);
 
+  // 5.5. 부수 이행 — .gitignore 누락 패턴 / TEST-GUIDE 이관. 둘 다 사용자 승인 후에만.
+  const gi = planGitignore(cwd, platforms);
+  if (gi.missing.length > 0) {
+    console.log(`\n  taskery 자산 중 .gitignore에 없는 항목: ${gi.missing.join(', ')}`);
+    console.log(`  (등록하지 않으면 이 파일들이 커밋에 섞여 들어갑니다.)`);
+    if (await confirm(`  .gitignore에 추가할까?`)) {
+      gi.apply();
+      console.log(`    .gitignore 갱신 — ${gi.missing.length}개 패턴 추가`);
+    }
+  }
+
+  const tg = planTestGuide(cwd);
+  if (tg.conflict) {
+    // 자동 병합은 사용자 파일을 훼손할 수 있어 하지 않는다. 다만 침묵하면 TEST-GUIDE에 쌓인
+    // 내용이 아무도 안 읽는 채로 남으므로 반드시 알린다.
+    console.log(
+      `\n  ⚠ .project/TEST-GUIDE.md(폐지)와 .project/rules/TEST_RULE.local.md가 모두 있습니다.`,
+    );
+    console.log(`     TEST-GUIDE 쪽 내용은 이제 아무 스킬도 읽지 않습니다 — 필요한 항목을 직접 옮겨주세요.`);
+  }
+  if (tg.available) {
+    console.log(`\n  .project/TEST-GUIDE.md는 0.7.0에서 폐지되고 역할이 TEST_RULE.local.md로 옮겨졌습니다.`);
+    console.log(`  지금 옮기지 않으면 /task-plan·/task-dev가 기존 내용을 읽지 않습니다. (원본은 보존)`);
+    if (await confirm(`  내용을 .project/rules/TEST_RULE.local.md로 이관할까?`)) {
+      const appended = tg.apply();
+      console.log(`    이관 완료 — .project/rules/TEST_RULE.local.md (원본 TEST-GUIDE.md 보존)`);
+      if (appended.length > 0) {
+        console.log(`    누락 절 골격 ${appended.length}개 추가(${appended.join(' / ')}) — 내용은 직접 채워주세요.`);
+      }
+    }
+  }
+
   const migratedFields = Object.entries(migration)
     .filter(([, added]) => added)
     .map(([k]) => k);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angar2/taskery",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Lightweight task system for Claude Code & Codex — 1 메인 세션(또는 멀티세션) + 스킬 9종 + catastrophic hook 안전망 2종",
   "bin": {
     "taskery": "bin/taskery.js",