@angar2/taskery 0.6.0 → 0.7.0

package/README.md

@@ -16,6 +16,9 @@ AI 코딩 에이전트의 자율 개발을 위한 Task 기반의 가드레일
 | 에이전트가 catastrophic 사고를 일으킬 수 있음 | 필수 hook으로 차단 — 정상 흐름에는 무간섭 |
 | 에이전트가 작성한 코드의 자가검증으로 인해 문제를 놓침 (confirmation bias) | 테스트 시 별도 격리 세션 호출(`/task-test`) — 메인 세션의 가정 없이 독립 검증 |
 | 단일 메인 세션 운영으로 인해 task를 직렬로 진행해야 하는 병목 | 같은 프로젝트에서 여러 메인 세션이 독립 작업 폴더(worktree)로 병렬 진행 — 머지 시점에 직렬화로 정합성 유지 |
+| 검수 중 한 줄만 고쳐도 전체 테스트를 다시 돌려 대기 시간이 길어짐 | 수정 구간에는 변경이 닿는 테스트만 실행 — 전체 실행은 task당 1회로 제한 |
+| 테스트가 앱 화면을 띄우고 조작해 그동안 컴퓨터를 쓸 수 없음 | 화면·입력을 점유하는 테스트는 창을 띄우지 않는 실행 경로가 준비된 경우에만 자동 실행 — 없으면 사용자 승인 후 실행 |
+| 프로젝트마다 개발·테스트 방식이 다른데 공통 규칙만 적용됨 | 프로젝트 전용 규칙 파일(`*.local.md`)을 각 스킬이 읽어 우선 적용 — 패키지를 갱신해도 덮어쓰지 않음 |
 
 > catastrophic 사고 예시 — git 운영 정책 위반, 검증 우회, 완료된 task 문서 재수정 등
 
@@ -105,7 +108,8 @@ taskery prune
 
 ```
 my-app/
-├─ CLAUDE.md                              # AI 에이전트 진입 문서
+├─ AGENTS.md                              # AI 에이전트 진입 문서 (본문 단일 소스)
+├─ CLAUDE.md                              # Claude Code용 — `@AGENTS.md` 임포트 한 줄
 ├─ .taskery-manifest.json                 # 패키지 업데이트 추적
 ├─ .gitignore
 ├─ .claude/
@@ -114,17 +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             # 이 프로젝트의 검증 실행 경로·범위 (모든 리포 필수)
     │   └─ *.local.md                     # 사용자 오버라이드 규칙 (패키지 업데이트 대상 제외)
     ├─ plans/                             # plan(기능 그룹)별 PLAN.md / ROADMAP.md (<NNN_slug>/)
     ├─ tasks/                             # task 문서 (<NNN_slug>/BACKLOG.md / spec-diffs / screenshots / mockup 포함)
@@ -133,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`에서 둘 다 선택하면 폴더가 갈려 충돌 없이 공존한다.
 
 ---
@@ -202,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` (사용자 명시 시 폴더 승격) |
 
@@ -231,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                  # 진입 메타 문서와 디렉토리 골격 생성
@@ -258,6 +265,7 @@ npx @angar2/taskery init
 - 사용자가 재구현을 요청하면 → `testing` → `developing`으로 회귀해 `/task-dev`가 자동 발동된다.
 - 사용자가 결함을 인지한 채 종결을 지시하면 → `testing` → `tested`로 진행하고 결함을 명시한 후 `/task-close`로 이행된다.
 - UNCERTAIN(자동 검증이 불가능한 시나리오)은 사용자가 직접 검수한 결과를 답하면 메인 세션이 PASS/FAIL로 해석해 위 두 흐름 중 하나로 합류시킨다.
+- 검증에 필요한 테스트가 화면·입력을 점유해 실행을 보류한 경우에는, 지금 실행할지 / 자리를 비울 때로 미룰지 / 창을 띄우지 않는 실행 경로를 마련할지를 사용자가 고른다. 승인 없이 임의로 실행하지 않는다.
 
 ---
 

package/bin/fork.js

@@ -57,8 +57,10 @@ async function main() {
     console.error(`type은 ${VALID_TYPES.join(' | ')} 중 하나 (받음: ${type})`);
     process.exit(1);
   }
-  if (!/^(BL-\d+|RM-\d+|DR)$/.test(src)) {
-    console.error(`src는 BL-NNN | RM-NNN | DR 형식 (받음: ${src})`);
+  // ST-N = 로드맵 Stage 출처 (ROADMAP은 Stage 단위·RM 채번 없음 — recordion FRICTION 2026-08-03 반영).
+  // RM-NNN은 구형 호환으로 계속 수용.
+  if (!/^(BL-\d+|RM-\d+|ST-\d+|DR)$/.test(src)) {
+    console.error(`src는 BL-NNN | ST-N(로드맵 Stage) | DR 형식 (받음: ${src}. 구형 RM-NNN도 호환)`);
     process.exit(1);
   }
   if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {

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 패턴 합성 (중복 제거)
@@ -247,7 +251,7 @@ function getWorktreesRoot(projectId) {
 }
 
 function getWorktreePath(projectId, { taskNum, src, slug }) {
-  // src = 'BL-NNN' | 'RM-NNN' | 'DR'
+  // 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}`);
 }
@@ -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']);
@@ -388,8 +413,9 @@ async function forkTask(mainWtPath, { type, dev, src, slug }) {
     if (parent === 'HEAD') {
       throw new Error('메인 워크트리가 detached HEAD — 부모로 삼을 브랜치에 체크아웃 필요.');
     }
-    // SSoT 안전망 — 같은 출처(BL-NNN/RM-NNN)가 이미 진행중이면 거부. DR은 별도 ID 없어 검사 제외.
-    if (src !== 'DR') {
+    // 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}) — 다른 세션이 같은 항목 진행`);
@@ -435,28 +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 등) 모두 가능.
+// 구형(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 버전\s*\n+([^\n]+)/);
-  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');
@@ -813,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);
@@ -847,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) {
@@ -902,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) {
@@ -1006,10 +1049,26 @@ function _porcelainFiles(wtPath) {
     .filter(Boolean);
 }
 
+// 빌드 산출물 판정 — 소스 변경에 도구가 따라 바꾸는 파생 파일 (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 }.
-  //   - 모든 코드 파일이 정확히 1 Phase에 매핑 → Phase 순서대로 자동 커밋.
-  //   - 미매핑/다중매핑/Phase 파싱 불가 → { ambiguous } 반환(커밋 X) → 스킬이 수동 처리.
+  // 매핑 폴백 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 };
@@ -1028,21 +1087,44 @@ function splitUncommittedByPhase(wtPath, taskMdPath, meta) {
       )
       .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) {
+    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: m.length === 0 ? `Phase 미매핑: ${f}` : `다중 Phase 매핑: ${f}`,
+        reason: `Phase 미매핑: ${f}`,
         files: codeFiles,
         phases: phases.map((p) => ({ num: p.num, name: p.name, files: p.files })),
       };
     }
-    fileToPhase[f] = m[0];
   }
+  // 규칙 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 codeFiles) {
+  for (const f of Object.keys(fileToPhase)) {
     const i = fileToPhase[f];
     if (!groups.has(i)) groups.set(i, []);
     groups.get(i).push(f);
@@ -1056,18 +1138,22 @@ function splitUncommittedByPhase(wtPath, taskMdPath, meta) {
     execFileSync('git', ['-C', wtPath, 'add', '--', ...grp], { stdio: 'pipe' });
     const msg =
       `${tag}: [TASK-${nnn}] Phase ${p.num} - ${p.name}\n\n` +
-      grp.map((f) => `- ${f}`).join('\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 });
   }
-  return { committed };
+  const result = { committed };
+  if (multiPhase.length > 0) result.multiPhase = multiPhase;
+  if (autoAssigned.length > 0) result.autoAssigned = autoAssigned;
+  return result;
 }
 
 async function closeTask(mainWtPath, { taskNum }, opts = {}) {
   // 결정적 준비만 — 비가역(머지·정리)·충돌 해결은 스킬이 후속 수행.
   // 반환: { blocked } (게이트 미충족/매핑 모호) 또는
-  //   { prepped, branch, parent, wtPath, registered, commits, aheadOfParent }. parent = 스킬 머지 대상.
+  //   { prepped, branch, parent, wtPath, registered, commits, aheadOfParent,
+  //     multiPhase?, autoAssigned? (매핑 폴백 적용 시 내역) }. parent = 스킬 머지 대상.
   const active = getActiveTasks(mainWtPath).find((t) => t.taskNum === taskNum);
   if (!active) {
     throw new Error(`TASK-${String(taskNum).padStart(3, '0')} 진행중 브랜치 없음 (SSoT 조회).`);
@@ -1158,7 +1244,7 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
     gitCapture(wtPath, ['rev-list', '--count', `${parent}..HEAD`], { allowFail: true }) || '0',
     10,
   );
-  return {
+  const prepResult = {
     prepped: true,
     taskNum,
     branch: active.branch,
@@ -1169,6 +1255,10 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
     commits,
     aheadOfParent: aheadFinal,
   };
+  // 매핑 폴백 적용 내역 노출 — 코드가 자동 편입한 걸 스킬·사용자가 볼 수 있게
+  if (split.multiPhase) prepResult.multiPhase = split.multiPhase;
+  if (split.autoAssigned) prepResult.autoAssigned = split.autoAssigned;
+  return prepResult;
 }
 
 module.exports = {
@@ -1207,6 +1297,7 @@ module.exports = {
   getInitLockPath,
   withMergeLock,
   withMetaLock,
+  withMetaLockSync,
   currentBranch,
   assertMainWorktreeOn,
   parseBranchName,
@@ -1217,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 게이트 무시'),
@@ -189,7 +189,7 @@ server.registerTool(
     inputSchema: {
       type: z.enum(VALID_TYPES),
       dev: z.string().describe('개발자 식별자 (claude / angar2 등)'),
-      src: z.string().regex(/^(BL-\d+|RM-\d+|DR)$/, 'BL-NNN | RM-NNN | DR'),
+      src: z.string().regex(/^(BL-\d+|RM-\d+|ST-\d+|DR)$/, 'BL-NNN | ST-N(로드맵 Stage) | DR (구형 RM-NNN 호환)'),
       slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
       size: z.enum(VALID_SIZES).optional(),
       title: z.string().optional().describe('한국어 제목 (size와 함께 주면 골격 생성)'),