@angar2/taskery 0.7.0 → 0.8.1

package/bin/migrate.js

@@ -5,11 +5,14 @@
  *
  * 이행 4종:
  *   1. ingestActivePlan  — 구형 AGENT-GUIDE.md '## 활성 plan 버전' → manifest.activePlan (1회)
- *   2. migrateEntryDocs  — 진입 문서 재편. 기존 CLAUDE.md/AGENTS.md의 *리포 값* 4섹션을 추출해
- *                          새 AGENTS.md에 주입하고, CLAUDE.md는 `@AGENTS.md` 한 줄로 축약.
+ *   2. recomposeEntryDocs — 진입 문서 **재조립**. 현 진입 문서(AGENTS.md, 없으면 구 CLAUDE.md)에서
+ *                          리포 내용을 건져 새 AGENTS.md 템플릿에 끼워넣는다. 최초 이행 때는
+ *                          CLAUDE.md를 `@AGENTS.md` 한 줄로 축약한다.
+ *                          **매 update 항상 실행한다(1회성 아님).** AGENTS.md는 리포 값을 품어
+ *                          템플릿과 바이트 일치가 원리적으로 불가능하므로, 본 루프의 복사 대상이
+ *                          되어선 안 된다(0.7.0 결함: 이행 후 본 루프가 값을 통째로 덮거나,
+ *                          거절하면 구판 문안에 영구 고착됐다).
  *                          **update 본 루프보다 먼저 실행하고, 처리한 경로를 본 루프에서 제외한다.**
- *                          본 루프에 맡기면 '사용자 customize 검출' 프롬프트가 뜨는데,
- *                          덮으면 리포 값이 .bak에만 남고 안 덮으면 구판 전문이 남아 새 판과 충돌한다.
  *   3. migrateGitignore  — AGENTS.md가 agnostic으로 바뀌어 모든 리포에 새로 깔리는데
  *                          .gitignore 기록은 init에만 있어 누락된다. 누락 패턴 append 제안.
  *   4. migrateTestGuide  — 폐지되는 TEST-GUIDE.md의 축적 내용을 TEST_RULE.local.md로 1회 이관.
@@ -20,7 +23,8 @@
 const fs = require('fs');
 const path = require('path');
 
-const { sha256, copyFile, gitignorePatternsFor } = require('./lib');
+const { sha256, sha256Text, copyFile, gitignorePatternsFor } = require('./lib');
+const { LEGACY_TEMPLATE_QUOTES } = require('./legacy-quotes');
 
 // 진입 문서에서 이식할 *리포 값* 섹션. 헤딩 텍스트 접두로 매칭한다 —
 // 실제 문서의 헤딩은 '## 검수 실행 명령 (해당 시 — 앱 실행·검수가 필요한 프로젝트)'처럼
@@ -59,52 +63,144 @@ function splitSections(content) {
   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();
+// 문서를 { 머리말, 섹션[] }로 쪼갠다. splitSections와 달리 첫 '## ' 앞의 머리말을 버리지 않는다 —
+// 재조립은 문서 전체를 다시 써내므로 머리말(제목·최상위 인용문)도 결과물에 들어가야 한다.
+function parseDoc(content) {
+  const preamble = [];
+  const sections = [];
+  let cur = null;
+  let inFence = false;
+  for (const line of content.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    const m = inFence ? null : line.match(/^##\s+(.*)$/);
+    if (m) {
+      cur = { heading: line, title: m[1].trim(), body: [] };
+      sections.push(cur);
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      preamble.push(line);
+    }
   }
-  while (body.length && body[0].trim() === '') body.shift();
-  return body.join('\n');
+  return { preamble, sections };
 }
 
-// 새 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 = [];
+// taskery가 쓴 인용문 집합 = 과거 템플릿 전량(고정 목록) ∪ *현재* 템플릿(실시간 추출).
+// 현재 템플릿을 함께 넣는 것이 핵심이다 — 그래야 다음 버전의 새 문안도 그 다음 update에서
+// 자기 자신을 중복 없이 걷어낸다(목록을 손으로 관리하지 않아도 영구히 자기유지된다).
+function boilerplateQuotes(templateContent) {
+  const set = new Set(LEGACY_TEMPLATE_QUOTES.map((s) => s.trim()));
+  for (const l of templateContent.split('\n')) {
+    if (/^\s*>/.test(l)) set.add(l.trim());
+  }
+  return set;
+}
+
+// 우리가 수행한 파일 이름 변경 — 리포가 직접 쓴 문장 안의 죽은 경로를 대응 경로로 바꾼다.
+// 1:1로 확정된 것만 넣는다(추측 치환 금지).
+const DEAD_PATH_REWRITES = [['.project/TEST-GUIDE.md', '.project/rules/TEST_RULE.local.md']];
+
+// 인용문 블록(헤딩 직후 연속된 '>' 줄)과 꼬리(끝의 빈 줄·구분선)를 템플릿 본문에서 뽑는다.
+function splitTemplateBody(body) {
   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++;
+  while (i < body.length && body[i].trim() === '') i++;
+  const quotes = [];
+  while (i < body.length && /^\s*>/.test(body[i])) quotes.push(body[i++]);
+  const tail = [];
+  let j = body.length - 1;
+  while (j >= i && (body[j].trim() === '' || body[j].trim() === '---')) tail.unshift(body[j--]);
+  return { quotes, tail };
+}
+
+/**
+ * AGENTS.md 재조립 — 새 템플릿의 지침 + 현 문서의 리포 내용.
+ *
+ * 절마다: 새 템플릿 헤딩 + 새 템플릿 인용문 + 현 문서 본문(단, taskery 인용문은 제거).
+ * 값 줄·표·산문은 판정 대상이 아니라 전부 보존된다. 리포가 직접 쓴 인용문도 보존된다.
+ *
+ * @returns {{ content, kept, dropped, rewritten, omitted, missing }}
+ *   kept — 보존한 리포 인용문 / dropped — 걷어낸 taskery 구 문안
+ *   rewritten — 죽은 경로를 치환한 줄 / omitted — 현 문서에 없어 결과물에서 뺀 절
+ *   missing — omitted 중 필수 절(호출자가 보류 판정에 쓴다)
+ */
+function composeAgentsDoc(currentContent, templateContent) {
+  const tpl = parseDoc(templateContent);
+  const cur = parseDoc(currentContent);
+  const boiler = boilerplateQuotes(templateContent);
+  const kept = [];
+  const dropped = [];
+  const rewritten = [];
+  const omitted = [];
+  const out = [...tpl.preamble];
+
+  for (const sec of tpl.sections) {
+    const key = REPO_VALUE_SECTIONS.find((k) => sec.title.startsWith(k));
+    if (!key) {
+      out.push(sec.heading, ...sec.body);
       continue;
     }
-    out.push(lines[i]); // 헤딩은 새 템플릿 것을 유지
-    i++;
-    // 기존 본문(다음 '## ' 직전까지)을 건너뛰면서, 끝의 빈 줄/구분선은 보존한다.
-    const skipped = [];
-    while (i < lines.length && !heads.has(i)) {
-      skipped.push(lines[i]);
-      i++;
+    const hit = cur.sections.find((s) => s.title.startsWith(key));
+    const { quotes, tail } = splitTemplateBody(sec.body);
+    if (!hit) {
+      // 리포가 지운 절은 되살리지 않는다(삭제 의사 존중). 절 사이 구분선만 유지한다.
+      omitted.push(key);
+      out.push(...tail);
+      continue;
+    }
+    const repoBody = [];
+    for (const raw of hit.body) {
+      const isQuote = /^\s*>/.test(raw);
+      if (isQuote && boiler.has(raw.trim())) {
+        dropped.push(raw.trim());
+        continue;
+      }
+      let line = raw;
+      for (const [from, to] of DEAD_PATH_REWRITES) {
+        if (line.includes(from)) line = line.split(from).join(to);
+      }
+      if (line !== raw) rewritten.push({ before: raw.trim(), after: line.trim() });
+      if (isQuote) kept.push(line.trim());
+      repoBody.push(line);
+    }
+    while (repoBody.length && repoBody[0].trim() === '') repoBody.shift();
+    while (
+      repoBody.length &&
+      (repoBody[repoBody.length - 1].trim() === '' || repoBody[repoBody.length - 1].trim() === '---')
+    ) {
+      repoBody.pop();
     }
-    const tail = [];
-    while (skipped.length && (skipped[skipped.length - 1].trim() === '' || skipped[skipped.length - 1].trim() === '---')) {
-      tail.unshift(skipped.pop());
+    out.push(sec.heading);
+    if (repoBody.length === 0) {
+      // 절은 있는데 내용이 비었다 → 새 템플릿 본문(플레이스홀더)을 그대로 쓴다.
+      out.push(...sec.body);
+      continue;
     }
-    out.push('', extracted[key], ...tail);
+    if (quotes.length) out.push('', ...quotes);
+    out.push('', ...repoBody, ...tail);
+  }
+
+  // 결과물에 실리지 않은 현 문서의 내용 — 리포 값 4개 절 *밖*에 사람이 적어 둔 줄이 여기 걸린다.
+  // 그 자리는 taskery 소유라 템플릿 판으로 덮이는 것이 설계지만, 재조립은 매 update 도는 상시
+  // 동작이므로 조용히 사라지면 안 된다. 버리되 반드시 알린다(.bak이 원본 참조처).
+  const inResult = new Set(out.map((l) => l.trim()));
+  const rewrittenBefore = new Set(rewritten.map((r) => r.before));
+  const unmapped = [];
+  for (const line of currentContent.split('\n')) {
+    const l = line.trim();
+    if (!l || l === '---') continue;
+    if (inResult.has(l) || boiler.has(l) || rewrittenBefore.has(l)) continue;
+    unmapped.push(l);
   }
-  return out.join('\n');
+
+  return {
+    content: out.join('\n'),
+    kept,
+    dropped,
+    rewritten,
+    omitted,
+    unmapped,
+    missing: omitted.filter((k) => !OPTIONAL_SECTIONS.has(k)),
+  };
 }
 
 /**
@@ -128,7 +224,7 @@ function ingestActivePlan(cwd, oldManifest) {
  *   handled — update 본 루프에서 제외할 설치 경로
  *   entries — manifest.files에 기록할 항목 (설치 경로 → { hash, core, managed })
  */
-function migrateEntryDocs(cwd, templateDir, platforms, oldManifest) {
+function recomposeEntryDocs(cwd, templateDir, platforms, oldManifest) {
   const notes = [];
   const entries = {};
   const skip = { handled: [], entries, notes, held: false, done: false };
@@ -137,63 +233,86 @@ function migrateEntryDocs(cwd, templateDir, platforms, oldManifest) {
   const claudePath = path.join(cwd, 'CLAUDE.md');
   const hasAgents = fs.existsSync(agentsPath);
   const hasClaude = fs.existsSync(claudePath);
-  if (!hasAgents && !hasClaude) return skip;
+  // 최초 이행 여부는 manifest 마커 하나로만 판정한다. 파일 구조로 추정하면 플랫폼별로 오판하고
+  // (codex 단독은 CLAUDE.md가 없다), 버전으로 거르면 보류된 리포가 영영 재시도되지 않는다.
+  const migrated = oldManifest.entryDocs === ENTRY_DOCS_MARKER;
 
-  // 이미 이행된 리포는 건너뛴다. 판정은 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));
+  // 조립 소스: 현 AGENTS.md가 최우선(이행 후의 정상 경로). 없으면 미이행 리포의 구 CLAUDE.md.
+  const srcPath = hasAgents ? agentsPath : hasClaude && !migrated ? claudePath : null;
+  if (!srcPath) return skip; // 진입 문서 자체가 없음 → 본 루프의 '신규' 분기가 템플릿을 깐다
+  const srcName = path.basename(srcPath);
 
   const newAgentsSrc = path.join(templateDir, 'AGENTS.md');
   const newAgents = fs.readFileSync(newAgentsSrc, 'utf8');
+  const current = fs.readFileSync(srcPath, 'utf8');
+  const composed = composeAgentsDoc(current, newAgents);
 
-  if (fatalMissing.length > 0) {
-    // 값 유실 방지 — 어느 파일도 덮지 않고 새 판을 .new로 남긴다. manifest도 갱신하지 않아
-    // 다음 update가 다시 시도한다.
+  // 최초 이행에서 필수 절을 못 찾으면 소스 판정이 틀렸다는 뜻이다 → 어느 파일도 덮지 않고 보류.
+  // (이행 후의 필수 절 부재는 사용자가 지운 것이므로 보류하지 않고 그 삭제를 존중한다.)
+  if (!migrated && composed.missing.length > 0) {
     fs.writeFileSync(path.join(cwd, 'AGENTS.md.new'), newAgents);
     notes.push(
-      `⚠ 진입 문서 이행 보류 — ${srcName}에서 필수 섹션을 찾지 못함 (${fatalMissing.join(', ')}).`,
+      `⚠ 진입 문서 이행 보류 — ${srcName}에서 필수 섹션을 찾지 못함 (${composed.missing.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');
+  // 결과물이 현 파일과 다를 때만 쓴다. .bak은 *최초 1회만* — 이미 있으면 그게 사용자의 원본이다.
+  const changed = !hasAgents || composed.content !== current;
+  if (changed) {
+    if (hasAgents && !fs.existsSync(agentsPath + '.bak')) {
+      fs.copyFileSync(agentsPath, agentsPath + '.bak');
+      notes.push(`   직전 AGENTS.md는 AGENTS.md.bak 으로 백업.`);
+    }
+    fs.writeFileSync(agentsPath, composed.content);
   }
-  fs.writeFileSync(agentsPath, injectSections(newAgents, extracted));
-  entries['AGENTS.md'] = { hash: sha256(newAgentsSrc), core: true, managed: true };
+  // manifest에는 **조립 결과물**의 해시를 기록한다. 템플릿 원본 해시를 적으면 실제 파일과
+  // 영구 불일치해 매 update마다 '사용자 customize' 오검출이 뜬다(0.7.0 결함).
+  entries['AGENTS.md'] = { hash: sha256Text(composed.content), 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(', ')})`);
+  if (!migrated) {
+    notes.push(
+      `진입 문서 재편 — ${srcName}의 리포 내용을 새 AGENTS.md로 재조립.`,
+      `   구 문서의 taskery 지침 본문은 새 체계(.project/rules/)로 대체됩니다 — 원본은 ${srcName}.bak.`,
+    );
+  } else if (changed) {
+    notes.push(`AGENTS.md 재조립 — 리포 내용 보존, taskery 지침만 새 판으로 교체.`);
+  }
+  if (changed) {
+    if (composed.dropped.length) {
+      notes.push(`   구 taskery 문안 ${composed.dropped.length}줄 제거(새 문안이 대체).`);
+    }
+    if (composed.kept.length) {
+      notes.push(`   리포가 직접 쓴 인용문 ${composed.kept.length}줄 보존.`);
+    }
+    for (const r of composed.rewritten) {
+      notes.push(`   경로 갱신: ${r.before}`);
+      notes.push(`          → ${r.after}`);
+    }
+    if (composed.omitted.length) {
+      notes.push(`   리포에 없어 결과물에서 뺀 절: ${composed.omitted.join(', ')} (되살리지 않음)`);
+    }
+    if (composed.unmapped.length && migrated) {
+      // 리포 값 칸 밖의 내용은 AGENTS.md가 소유하지 않는다(TASKERY_RULE — 규칙은 rules/, 커스텀은 *.local.md).
+      // 그래도 사람이 적어 둔 것이므로 전량을 보여주고 원본 위치를 알린다.
+      // 최초 이행에서는 알리지 않는다 — 그때의 미반영분은 전량이 *구 taskery 문서 본문*이라
+      // (0.6.1 기준 88줄) 경고가 아니라 노이즈다. 그 경우는 아래 한 줄과 .bak으로 갈음한다.
+      notes.push(
+        `   ⚠ 리포 값 칸(프로젝트 메타 · 각 명령) 밖의 아래 ${composed.unmapped.length}줄은 결과물에 싣지 않았습니다.`,
+        `     그 자리는 taskery 지침 영역이라 새 판으로 교체됩니다. 남길 내용이면 값 칸이나 *.local.md로 옮기세요.`,
+        `     (직전 원본: AGENTS.md.bak)`,
+      );
+      for (const l of composed.unmapped) notes.push(`       · ${l.length > 96 ? l.slice(0, 96) + '…' : l}`);
+    }
   }
 
   const handled = ['AGENTS.md'];
 
-  // CLAUDE.md는 `@AGENTS.md` 한 줄로 축약 (claude 플랫폼일 때만).
-  if (platforms.includes('claude')) {
+  // CLAUDE.md는 `@AGENTS.md` 한 줄로 축약 — 최초 이행 때 1회(claude 플랫폼일 때만).
+  // 이행 후에는 순수 템플릿 파일이라 본 루프가 정상 관리한다.
+  if (!migrated && platforms.includes('claude')) {
     const claudeSrc = path.join(templateDir, 'CLAUDE.md');
     if (hasClaude && !fs.existsSync(claudePath + '.bak')) {
       fs.copyFileSync(claudePath, claudePath + '.bak');
@@ -208,6 +327,22 @@ function migrateEntryDocs(cwd, templateDir, platforms, oldManifest) {
   return { handled, entries, notes, held: false, done: true };
 }
 
+/**
+ * 2-b. 구형 AGENT-GUIDE.md 정리 — 활성 plan이 manifest로 이관된 뒤에도 남아 있으면
+ *      같은 정보를 두 곳에 보유하게 되고, manifest 값이 비는 순간 lib의 구형 폴백이
+ *      낡은 값을 되살린다. 삭제는 하지 않고(사용자 파일 불가침) 이름을 바꿔 폴백 경로에서 뺀다.
+ * @returns {string|null} 처리 안내 (해당 없으면 null)
+ */
+function retireLegacyAgentGuide(cwd, activePlan) {
+  if (!activePlan) return null; // manifest가 아직 활성 plan을 못 들었으면 폴백을 남겨둔다
+  const guidePath = path.join(cwd, '.project', 'AGENT-GUIDE.md');
+  if (!fs.existsSync(guidePath)) return null;
+  const retired = guidePath + '.obsolete';
+  if (fs.existsSync(retired)) return null;
+  fs.renameSync(guidePath, retired);
+  return `구형 .project/AGENT-GUIDE.md 는 활성 plan이 manifest로 이관돼 역할이 끝났습니다 — AGENT-GUIDE.md.obsolete 로 이름 변경(내용 보존). 확인 후 삭제해도 됩니다.`;
+}
+
 /**
  * 3. .gitignore 누락 패턴 — 이미 taskery 패턴을 쓰는 리포에만 제안한다.
  *    (init에서 등록을 거부한 리포는 패턴이 하나도 없으므로 건드리지 않는다.)
@@ -231,11 +366,39 @@ function planGitignore(cwd, platforms) {
   };
 }
 
+// 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 }}
+ * @returns {{ available: boolean, apply: function }} — apply()는 append한 필수 절 key 목록을 반환
  */
 function planTestGuide(cwd) {
   const guidePath = path.join(cwd, '.project', 'TEST-GUIDE.md');
@@ -260,8 +423,18 @@ function planTestGuide(cwd) {
         '> `*.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);
+      fs.writeFileSync(localPath, header + stripped + tail);
+      return appended.map((s) => s.key);
     },
   };
 }
@@ -297,10 +470,12 @@ module.exports = {
   mergeGitignore,
   isBefore070,
   splitSections,
-  findSectionBody,
-  injectSections,
+  parseDoc,
+  boilerplateQuotes,
+  composeAgentsDoc,
   ingestActivePlan,
-  migrateEntryDocs,
+  retireLegacyAgentGuide,
+  recomposeEntryDocs,
   planGitignore,
   planTestGuide,
 };

package/bin/update.js

@@ -42,7 +42,8 @@ const {
   ENTRY_DOCS_MARKER,
   mergeGitignore,
   ingestActivePlan,
-  migrateEntryDocs,
+  retireLegacyAgentGuide,
+  recomposeEntryDocs,
   planGitignore,
   planTestGuide,
 } = require('./migrate');
@@ -91,11 +92,11 @@ 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);
+  // 2.5. 진입 문서 재조립 — **본 루프보다 먼저, 그리고 매 update 항상.**
+  //   AGENTS.md는 리포 값을 품어 템플릿과 바이트 일치가 원리적으로 불가능하다. 본 루프에 맡기면
+  //   '사용자 customize 검출'이 떠서, 덮으면 리포 값이 .bak에만 남고 거절하면 구판 문안에 고착된다.
+  //   재조립이 최종 상태까지 기록하고, 처리한 경로는 아래 루프에서 제외한다.
+  const entryMig = recomposeEntryDocs(cwd, templateDir, platforms, oldManifest);
   const entryHandled = new Set(entryMig.handled);
   for (const line of entryMig.notes) console.log(`  ${line}`);
   Object.assign(newFiles, entryMig.entries);
@@ -212,6 +213,8 @@ async function main() {
   // 소리 없이 사라지고 구형 AGENT-GUIDE 폴백의 낡은 값으로 되돌아간다.
   const { activePlan, ingested: activePlanIngested } = ingestActivePlan(cwd, oldManifest);
   if (activePlanIngested) migration.activePlan = true;
+  const retiredGuide = retireLegacyAgentGuide(cwd, activePlan);
+  if (retiredGuide) console.log(`\n  ${retiredGuide}`);
 
   const newManifest = {
     version: getPackageVersion(),
@@ -252,8 +255,11 @@ async function main() {
     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로 이관할까?`)) {
-      tg.apply();
+      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(' / ')}) — 내용은 직접 채워주세요.`);
+      }
     }
   }
 

package/package.json

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

package/template/.codex/agents/task-tester.toml

@@ -10,19 +10,25 @@
 #
 # ⚠ model 명시 필수 — 생략하면 자식 모델 resolve가 service tier validation에서 실패한다.
 #   환경의 사용 가능 모델에 맞게 조정한다(기본 gpt-5.5).
+#
+# ⚠ sandbox_mode = workspace-write — 음성 대조(펜스 룰 19: 구현 일시 되돌림 → FAIL 확인 → 즉시 원복)가
+#   쓰기를 요구해 read-only에서 workspace-write로 전환. 코드 수정 금지 원칙(룰 8)은 유지되며 룰 19가
+#   유일 예외(원복 의무 + 메인 측 전후 스냅샷 대조가 안전망).
 
 name = "task-tester"
 description = "격리 검증 에이전트. 메인의 확증편향 없이 task.md + TEST_RULE.local.md를 보고 Test Plan을 증거 기반으로 독립 수행한다. /task-test가 spawn한다."
 model = "gpt-5.5"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """
 너는 격리된 tester다. 메인 세션의 가정(plan/dev 컨텍스트, "잘 될 거야")을 일체 신뢰하지 말고, 넘겨받은 검사 지시(spawn prompt)와 문서만 보고 자기완결적으로 검증하라.
 
 검사 룰의 단일 소스 = spawn 시 넘겨받은 검사 지시(prompt)다. 그것을 그대로 따르며, 아래는 그 핵심을 코덱스에서 동일하게 보장하는 기준선이다(넘겨받은 지시와 충돌 시 넘겨받은 지시 우선):
 
-- 넘겨받은 task.md와 TEST_RULE.local.md를 직접 읽는다(task.md가 목업을 참조하면 목업도). "task.md 하나만"이 아니다 — TEST_RULE.local.md는 각 검증 방식을 *이 프로젝트에서 실제로 어떻게 실행하나*(DB 조회 경로 / API 호출법 / E2E 셋업 / 시각 실행)의 단일 소스다.
+- 넘겨받은 task.md와 TEST_RULE.local.md를 직접 읽는다(task.md가 목업을 참조하면 목업도, 시험지 원본 경로가 주어졌으면 그것도). "task.md 하나만"이 아니다 — TEST_RULE.local.md는 각 검증 방식을 *이 프로젝트에서 실제로 어떻게 실행하나*(DB 조회 경로 / API 호출법 / E2E 셋업 / 시각 실행)의 단일 소스다.
 - task.md의 ## Test Plan 시나리오를 순서대로 그대로 수행한다(임의 추가/스킵/변형 금지).
-- 문 앞 검사(먼저) — 각 [AUTO] 시나리오가 [실행 명령/입력 + 구체적·관측 가능한 기대값(출력값/상태코드/어서션/조회 결과/화면 상태)] 한 쌍을 갖췄는지 확인한다. "정상 동작/잘 됨/확인한다" 같은 소원은 기대값이 아니다. 미달인 [AUTO]는 검사하지 말고 "시험문제 결함(검증 불가)"으로 분류 + 무엇이 빠졌는지 지목한다(PASS 반올림 금지).
+- 문 앞 검사(먼저) — 각 [AUTO] 시나리오가 [실행 명령/입력 + 구체적·관측 가능한 기대값(출력값/상태코드/어서션/조회 결과/화면 상태)] 한 쌍을 갖췄는지 확인한다. "정상 동작/잘 됨/확인한다" 같은 소원은 기대값이 아니다. UX/UI task의 [AUTO] 기대값은 출처 표기("(출처: 목업 §N / Req N)")도 자격 요건 — 무표기·"(출처 없음 — 사용자 확인 필요)" 잔존은 자격 미달. 미달인 [AUTO]는 검사하지 말고 "시험문제 결함(검증 불가)"으로 분류 + 무엇이 빠졌는지 지목한다(PASS 반올림 금지).
+- 시험지 오염 대조(시험지 원본 경로가 주어졌을 때, 먼저) — 원본을 Read해 task.md ## Test Plan과 칸 단위 대조. 무플래그 차이 = 무조건 오염 즉시 반려. 플래그 칸은 종류별 검증 — 【A수정】은 방식 칸만 허용(원안 문자열이 원본과 일치해야 하며 시나리오·PASS 기준의 A수정 = 오염), 【사용자결정】·【보수】는 허용 경로(원안 표기 일치만 확인). 방식 교체를 빙자해 기대값·시나리오 의미가 함께 바뀌었으면 오염. 오염 = UNCERTAIN(검증 불가) + "시험지 오염" 라벨로 리턴(어느 칸이 어떻게 다른지 명시).
+- 음성 대조(핵심 시나리오 최소 1개 — 코드 수정 금지의 유일 예외) — 구현 코드를 일시 되돌린 상태에서 그 시나리오가 실제로 FAIL함을 확인한 후 즉시 원복하고 통과 근거에 포함한다(git 명령 금지, 종료 시 되돌림 흔적 0 의무 — 원복 후 스스로 diff 확인). 되돌리기가 위험한 영역이면 생략 + 사유 기록.
 - 증거 일치 시만 PASS — 자격 갖춘 [AUTO]는 실제로 실행해 *관측 결과가 기대값과 일치할 때만* PASS. 코드 정독 "그럴듯함"·추정으로 PASS 금지. 증거(명령 출력/응답 로그/캡처/조회 결과)를 첨부한다.
 - [AUTO]/[USER] 분류 — [USER]는 정답지가 *주관*인 것만(시각 미세 취향 / 색조·2px / UX 느낌) → UNCERTAIN(사람 검수) + 증거 캡처로 리턴. 시각 *객관* 깨짐(요소 빠짐/빈 화면/배치 딴판/색 완전히 틀림)은 [USER]가 아니라 [AUTO] — 실제 화면 캡처 → 승인 목업과 대조해 네가 직접 판정한다(어긋나면 *구체적 어긋남 목록* + FAIL). 시각이라고 무조건 사람에게 넘기지 마라. 단 시각 객관의 [AUTO] 승격은 TEST_RULE.local.md의 *시각 실행* 절에 캡처 실행 경로가 있을 때 한정이다 — 경로가 없어 task.md가 [USER]로 분류했으면 그 분류를 존중한다.
 - UNCERTAIN 세 종류 — (사람 검수)=정답지가 주관인 영역 / (검증 불가)=[AUTO]인데 대조할 기대값을 구성 못 함=시험문제 결함 / (실행 보류)=화면·입력 점유 제약으로 실행하지 않음=환경 제약(사용자 승인 또는 격리 실행 경로 필요. 무엇을 왜 실행하지 않았는지 기록해 리턴). 검증 불가는 PASS로 반올림하거나 사람 검수로 떠넘기지 말고, *무엇을 시도했고 왜 기대값을 구성할 수 없는지* 근거를 반드시 기록한다(task-plan으로 Test Plan을 보수해야 하는 신호).
@@ -30,6 +36,6 @@ developer_instructions = """
 - 픽스처 현실성 — 픽스처·시드가 실제 산출물과 형식·정밀도가 같은지 의심하고, 의심되면 실제 코드(writer·생성기)로 재생성해 재실행한 결과로 판정한다. 재생성 경로가 없어 대조를 구성할 수 없으면 시험문제 결함(검증 불가)으로 분류한다.
 - 어서션 정면성 — 기대값이 요구사항을 정면으로 겨누는지 확인한다("벗어날 수 없다"면 실제로 벗어나 볼 것. 버튼 disabled 확인은 우회 지표다). 우회 지표로 검사하는 [AUTO] 시나리오는 시험문제 결함으로 분류하고 무엇이 정면 관측인지 지목한다.
 - 화면·입력 점유 금지 — 실제 앱을 띄워 UI를 자동 조작하는 스위트는 사용자의 화면·입력을 점유한다. TEST_RULE.local.md의 *테스트 실행 환경* 절에 격리 실행 경로(창 숨김·헤드리스 / 컨테이너 / VM / CI)가 있으면 그 경로로 실행하고, 없으면 비점유 부분만 실행하거나 실행 보류(사용자 승인 필요)로 표시해 리턴한다. 헤드리스 모드가 있으면 항상 그쪽을 쓴다.
-- 코드와 동작만 신뢰한다. 코드 파일 수정 금지. 임시 파일(테스트 스크립트 등)은 종료 후 삭제한다.
+- 코드와 동작만 신뢰한다. 코드 파일 수정 금지(유일 예외 = 위 음성 대조의 일시 되돌림 — 즉시 원복). 임시 파일(테스트 스크립트 등)은 종료 후 삭제한다.
 - 검증을 마치면 넘겨받은 검사 지시의 결과 형식(종합 판정 PASS/FAIL/UNCERTAIN / 시나리오별 결과 / 검증·테스트 명령 결과 / UNCERTAIN 3종 / 시험문제 결함 / 실행 보류)을 그대로 리턴한다.
 """

package/template/.codex/agents/test-plan-author.toml

@@ -0,0 +1,34 @@
+# taskery 출제 분리 서브에이전트 — /task-plan Step 5-B가 spawn하는 독립 Test Plan 출제자(B)
+#
+# 클로드의 "서브에이전트 격리 호출"에 대응하는 코덱스 서브에이전트 정의.
+# 구현자(A=메인)가 출제를 겸하면 같은 오독이 문제지와 답안지에 함께 들어가므로,
+# B는 Requirements 합의문 + 승인 목업 + TEST_RULE.local.md만 보고 출제한다 (Dev Plan·코드 접근 없음).
+#
+# ⚠ 미러 — 아래 developer_instructions는 `.agents/skills/task-plan/SKILL.md` Step 5-B의 B prompt 펜스와
+#   *같은 효과*를 내야 한다. /task-plan은 그 펜스 전체를 spawn prompt(task)로 전달하므로 펜스가 단일 룰
+#   소스이며, 이 지침은 코덱스에서 동일 효과를 보장하는 기준선이다. 펜스의 룰이 바뀌면 이 지침도 함께 갱신한다.
+#   (클로드 = 서브에이전트 격리 호출 + 펜스 / 코덱스 = 본 에이전트 + 펜스 — 양쪽 동일 효과)
+#
+# ⚠ model 명시 필수 — 생략하면 자식 모델 resolve가 service tier validation에서 실패한다.
+#   환경의 사용 가능 모델에 맞게 조정한다(기본 gpt-5.5).
+
+name = "test-plan-author"
+description = "출제 분리 에이전트(B). Requirements 합의문 + 승인 목업 + TEST_RULE.local.md만 보고 Test Plan을 출제한다 — 구현 계획·코드 접근 없음. /task-plan Step 5-B가 spawn한다."
+model = "gpt-5.5"
+sandbox_mode = "read-only"
+developer_instructions = """
+너는 격리된 Test Plan 출제자(B)다. 구현 계획·코드에 대한 어떤 가정도 없이, spawn prompt에 명시된 자료만 보고 검증 시나리오를 출제하라.
+
+출제 룰의 단일 소스 = spawn 시 넘겨받은 출제 지시(prompt)다. 그것을 그대로 따르며, 아래는 그 핵심을 코덱스에서 동일하게 보장하는 기준선이다(넘겨받은 지시와 충돌 시 넘겨받은 지시 우선):
+
+- 입력은 prompt에 인라인된 Requirements 합의문 + (있을 때만) 승인 목업 경로 + 검증 규칙(TEST_RULE.local.md) 경로뿐이다. task 문서·코드·기타 문서를 열지 않는다. Requirements에 적힌 것만 검증 대상 — 적히지 않은 요구를 추정해 시나리오를 만들지 않는다.
+- 검증 규칙 파일이 주어졌으면 반드시 Read — ① 방식별 실행 경로 ② 테스트 실행 환경(점유 스위트 격리 경로·사용자 결정 기록) ③ 범위·방식 정책.
+- 시나리오 형식 = [실제 실행할 명령/입력] + [구체적·관측 가능한 기대값] 한 쌍 강제. "정상 동작/잘 됨" 같은 소원 금지. 장면 쪼개기 — 진짜 떨어질 장면 여러 개로 분해.
+- 방식 선택은 기계적으로 — 화면 신규·변경=시각(캡처-목업 대조) / 상호작용=UI 동작 / 엔드포인트=API 호출 / 데이터 변경=사이드 이펙트 조회 / 순수 계산=입출력 비교 / 기존 영역=회귀. 여러 개 걸리면 다 붙인다.
+- 방식 칸은 검증 규칙의 "방식별 실행 경로" 절에 등재된 경로로 채운다. 등재 경로가 없으면 그 칸에 "등재 경로 없음 — 메인 확인 필요"라고 적는다(실행 경로를 지어내지 않는다).
+- 어서션 정면성 — 기대값이 요구사항 자체를 관측해야 한다. "벗어날 수 없다"면 실제로 벗어나 보는 것이 정면, disabled 확인 같은 우회 지표는 PASS 기준이 될 수 없다.
+- 기대값 출처 표기 — UX/UI 요구의 모든 [AUTO] PASS 기준 끝에 출처를 단다: "(출처: 목업 §N / Req N)". 달 수 없으면 "(출처 없음 — 사용자 확인 필요)"로 표기한다(추정 은폐 금지).
+- 화면·입력 점유 스위트는 검증 규칙 "테스트 실행 환경" 절의 현재 기록 기준으로 분류한다 — 격리 경로 선언 있음=[AUTO] / "없음 — 매번 승인" 기록 또는 무기록=시나리오에 "사용자 승인 후 실행" 표기(사용자 질문은 메인 몫).
+- grep/Read-only 존재 확인 시나리오는 보조용 — 단독 PASS 가치 없음. Requirements 각 항목당 end-to-end 실동작 시나리오 최소 1개.
+- 출력은 넘겨받은 출제 지시의 출력 형식 그대로 — ## Test Plan 표(시나리오/분류/방식/PASS 기준) + Requirements ↔ Test Plan 매트릭스. 코드·문서 수정 금지 — 출제만 하고 리턴한다.
+"""