@angar2/taskery 0.6.1 → 0.8.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/close.js

@@ -8,10 +8,11 @@
  * 코드가 수행하고 멈춘다. 이후 비가역(사전 rebase+충돌해결 / 머지 락 / 부모 --no-ff 머지 /
  * worktree remove / branch -d)은 스킬(task-close)이 git-guard hook + 복구출력 보호 하에 수행.
  *
- * stdout: { prepped, branch, parent, wtPath, registered, commits, aheadOfParent }. parent = 머지 대상. exit 0.
+ * stdout: { prepped, branch, parent, wtPath, registered, commits, aheadOfParent, changelog }. parent = 머지 대상. exit 0.
  * 콜백(스킬이 LLM 판단 후 처리):
  *   - exit 3 + { blocked:'status', current }  — status가 tested 아님 (게이트 차단)
  *   - exit 2 + { blocked:'mapping', files, phases, reason } — Phase↔파일 매핑 모호 (수동 커밋 필요)
+ *   - exit 4 + { blocked:'docs', missing }    — PLAN 체크·수정이력 누락 (문서 채운 후 그대로 재호출)
  * 그 외 실패 시 stderr + exit 1.
  */
 
@@ -60,10 +61,21 @@ async function main() {
     process.stdout.write(JSON.stringify(result) + '\n');
     process.exit(3);
   }
+  if (result.blocked === 'docs') {
+    console.error(`문서 게이트 차단 — 아래 문서에 TASK 표기 누락. 채운 후 그대로 재호출(변이 없음).`);
+    for (const miss of result.missing) {
+      console.error(`  - [${miss.kind === 'plan' ? 'PLAN 체크리스트' : '수정 이력'}] ${miss.file}`);
+    }
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(4);
+  }
   if (result.blocked === 'mapping') {
     console.error(
       `Phase↔파일 매핑 모호 (${result.reason}) — Dev Plan '파일' 필드 확인 후 수동 Phase 커밋 필요.`,
     );
+    console.error(
+      `미매핑 파일이 Dev Plan에 적혀 있다면 '- 파일:' 표기 형식(쉼표/가운뎃점/들여쓴 목록)을 확인 — 줄 전체가 경로 하나로 읽혔을 수 있습니다.`,
+    );
     process.stdout.write(JSON.stringify(result) + '\n');
     process.exit(2);
   }

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) {
@@ -968,10 +1007,22 @@ const TAG_OF = {
 
 function _parseDevPlanPhases(content) {
   // ## Dev Plan 섹션의 `### Phase N — 이름` + `- 파일:` 필드 추출.
+  // 다중 파일 표기 지원 — 한 줄(쉼표·가운뎃점 `·` 구분) + `- 파일:` 다음의 들여쓴 하위 목록.
+  // `/`는 경로 문자라 분할자로 쓰지 않는다. `(신규)`류 꼬리 괄호 주석은 제거한다.
   const lines = content.split('\n');
   let inDevPlan = false;
   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;
@@ -983,15 +1034,23 @@ function _parseDevPlanPhases(content) {
     if (ph) {
       cur = { num: parseInt(ph[1], 10), name: ph[2].trim(), files: [] };
       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) {
-      cur.files = fm[1]
-        .split(',')
-        .map((s) => s.replace(/`/g, '').trim())
-        .filter((s) => s && !/^[(<]/.test(s)); // placeholder(<...>, (...)) 제외
+      fileIndent = fm[1].length;
+      if (fm[2].trim()) pushFiles(fm[2]);
+      continue;
+    }
+    if (fileIndent != null) {
+      const sub = l.match(/^(\s+)-\s+(.+)$/);
+      if (sub && sub[1].length > fileIndent) {
+        pushFiles(sub[2]);
+        continue;
+      }
+      fileIndent = null; // 다른 필드·비목록 줄에서 하위 목록 수집 종료
     }
   }
   return phases;
@@ -1110,10 +1169,116 @@ function splitUncommittedByPhase(wtPath, taskMdPath, meta) {
   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(),
+    '',
+    `- **날짜**: ${_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 });
+        }
+      }
+    }
+  }
+  return missing.length ? { ok: false, missing } : { ok: true };
+}
+
 async function closeTask(mainWtPath, { taskNum }, opts = {}) {
   // 결정적 준비만 — 비가역(머지·정리)·충돌 해결은 스킬이 후속 수행.
-  // 반환: { blocked } (게이트 미충족/매핑 모호) 또는
-  //   { prepped, branch, parent, wtPath, registered, commits, aheadOfParent,
+  // 순서: 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) {
@@ -1133,6 +1298,13 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
     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) {
@@ -1149,6 +1321,15 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
   // 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')),
+  });
+
   const commits = [...split.committed];
   // 미등록 케이스: .project/ 변경분(flows / 문서 / changelog)을 커밋
   if (!resolved.registered) {
@@ -1215,6 +1396,7 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
     docPath: resolved.file,
     commits,
     aheadOfParent: aheadFinal,
+    changelog,
   };
   // 매핑 폴백 적용 내역 노출 — 코드가 자동 편입한 걸 스킬·사용자가 볼 수 있게
   if (split.multiPhase) prepResult.multiPhase = split.multiPhase;
@@ -1258,6 +1440,7 @@ module.exports = {
   getInitLockPath,
   withMergeLock,
   withMetaLock,
+  withMetaLockSync,
   currentBranch,
   assertMainWorktreeOn,
   parseBranchName,
@@ -1268,6 +1451,7 @@ module.exports = {
   // 백로그 (0.1.2+)
   BACKLOG_PLACEHOLDER,
   getActiveVersion,
+  setActivePlan,
   getBacklogPath,
   computeNextBLNumber,
   formatBacklogBlock,
@@ -1288,5 +1472,7 @@ module.exports = {
   // task close 결정적 준비 (D1·D2)
   TAG_OF,
   splitUncommittedByPhase,
+  appendChangelogEntry,
+  checkDocsGate,
   closeTask,
 };

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 게이트 무시'),