@angar2/taskery 0.7.0 → 0.8.1

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/legacy-quotes.js

@@ -0,0 +1,60 @@
+// 과거 taskery 진입 문서 템플릿이 쓰던 인용문 목록 — 재조립 시 리포 소유 문장과 구별하는 기준
+/**
+ * bin/legacy-quotes.js
+ * v0.1.0~v0.8.0의 `template/CLAUDE.md`·`template/AGENTS.md`에 실렸던 `>` 인용문 전량(유니크 42줄).
+ *
+ * 쓰임: AGENTS.md 재조립(migrate.composeAgentsDoc)에서 리포 문서의 인용문을 판정한다.
+ *   - 이 목록 또는 *현재 템플릿*에 있는 문장 → taskery가 쓴 것 → 버리고 새 문안으로 교체
+ *   - 어느 쪽에도 없는 문장 → 리포가 쓴 것 → 그대로 보존
+ * 판정 실패는 **보존 쪽으로 실패한다** — 목록에 없으면 남긴다(중복은 눈에 띄지만 유실은 복구 불가).
+ *
+ * 생성 방법(재현): 각 릴리스 태그에서 두 템플릿의 `^> ` 줄을 뽑아 정렬·유니크.
+ * 새 버전의 문안은 목록에 추가할 필요가 없다 — 재조립이 현재 템플릿에서 실시간으로 읽는다.
+ */
+
+const LEGACY_TEMPLATE_QUOTES = [
+  '> **검증 방법 → `.project/TEST-GUIDE.md`** — 각 테스트 방식(데이터 조회 / API 호출 / E2E / 시각 실행)을 *이 프로젝트에서 실제로 어떻게 돌리나*는 거기 단일 소스. `/task-plan`이 채우고 `/task-test` 격리 세션이 읽는다.',
+  '> **본 문서에는 규칙·사용법을 추가하지 않는다** — 규칙은 `.project/rules/`, 이 리포의 커스텀은 `*.local.md`가 담당한다. 본 문서에서 갱신이 허용되는 것은 아래 리포 값 칸(프로젝트 메타 · 각 명령)뿐이다.',
+  '> *코드 상태 검증* (빌드 / 린트 / 타입체크). 테스트 실행은 본 섹션 X — `## 테스트 명령` 참조.',
+  '> *테스트 실행* (단위 / 통합 / E2E 등). 코드 상태 검증은 `## 검증 명령` 참조.',
+  '> - Hook: `.codex/config.toml`의 `[[hooks.PreToolUse]]`로 등록 — 최초 1회 `/hooks` trust 승인 필요',
+  '> - 격리 검증(/task-test): `.codex/agents/task-tester.toml` 서브에이전트로 spawn',
+  '> - 스킬 본문: `.agents/skills/<스킬>/SKILL.md` (Claude의 `.claude/skills/`가 아님)',
+  '> CLI/라이브러리 등 검수 서버가 없는 프로젝트는 본 섹션 전체 삭제.',
+  '> Codex 환경 차이 (Claude와 다른 점만):',
+  '> `.codex/config.toml`의 `[[hooks.PreToolUse]]`로 등록. 최초 1회 `/hooks` trust 승인 후 자동 작동.',
+  '> `.project/tasks/<NNN_slug>/BACKLOG.md` = *plan(기능 그룹)별 task 후보 누적*. 사용자 발화로 1건씩 얕은 분석(개요 / 대상 영역) 곁들여 추가.',
+  '> `.project/tasks/<vX.X>/BACKLOG.md` = *버전별 task 후보 누적*. 사용자 발화로 1건씩 얕은 분석(개요 / 대상 영역) 곁들여 추가.',
+  '> `/project-init` 호출 시 위 4 항목 채워짐. 변경 필요하면 직접 Edit.',
+  '> `/project-init` 호출 시 위 4 항목 채워짐. 변경 필요하면 직접 편집.',
+  '> `/run-team`은 Claude 전용 — agent teams(실험 기능)가 Codex에 없어 Codex 설치에는 미포함.',
+  '> `/task-dev` self-check / `/task-close` 최종 게이트가 *이 섹션을 단일 진실 소스로 참조*.',
+  '> `/task-dev` self-check / `/task-test` 격리 게이트 / `/task-close` 최종 게이트 / `pre-commit-verify.sh` hook이 *모두 이 섹션을 단일 진실 소스로 참조*.',
+  '> `/task-dev` 구현 후 테스트 + `/task-test` 격리 세션이 *이 섹션을 단일 진실 소스로 참조*.',
+  '> `/task-dev`·`/task-test`가 검수 시점(세션 중단점)에 이 명령으로 서버를 *백그라운드* 기동하고 접속 URL을 보고한다.',
+  '> closed-immutable.sh는 코덱스 파일편집 도구(apply_patch)의 patch envelope에서 `*** Update File:` 경로를 파싱해 검사한다(Claude판은 `file_path` 키를 읽음 — 메커니즘만 다르고 효과 동일).',
+  '> taskery는 *plan/ ↔ template/ 자동 빌드 X*. 사용자가 직접 정합 유지.',
+  '> 각 명령은 그대로 실행 가능한 형태로 적는다. 해당 없는 항목은 행을 삭제한다.',
+  '> 다건 태스크를 *리더 메인 세션 1개가 agent teams로 팀원(독립 세션)에 분배*해 자동 병렬 처리하는 고기능. 위 멀티세션을 사용자가 일일이 띄우는 대신 리더가 띄우고 관리한다. 워크트리 격리·머지 직렬화는 기존 `/task-init`·`/task-close`가 그대로 담당.',
+  '> 다건 태스크를 리더가 팀원(독립 세션)에 분배해 자동 병렬 처리하는 고기능(`/run-team`)은 **Claude 전용**이다 — 기반인 agent teams 기능이 Codex에 없다.',
+  '> 멀티세션 = 같은 프로젝트에서 *여러 메인 세션이 독립 태스크를 병렬*로 진행. git worktree로 작업 폴더 격리, dev 머지 시 직렬화.',
+  '> 멀티세션 = 같은 프로젝트에서 *여러 메인 세션이 독립 태스크를 병렬*로 진행. git worktree로 작업 폴더 격리, 부모 브랜치 머지 시 직렬화.',
+  '> 멀티세션 포트 격리: 메인 세션(부모 브랜치) = 기준 포트, task 워크트리 = 기준 포트 + TASK번호. 상세는 GIT_RULE "멀티세션 검수 환경" 섹션.',
+  '> 멀티세션 포트 격리: 메인/dev 세션 = 기준 포트, task 워크트리 = 기준 포트 + TASK번호. 상세는 GIT_RULE "멀티세션 검수 환경" 섹션.',
+  '> 백틱(`...`) 안 명령 그대로 실행됨. 언어/프레임워크 따라 변경.',
+  '> 본 룰은 *모든 스킬 호출 / 사용자 발화 처리 / 작업 진행*에 적용. 위반 시 사용자 마찰 직결.',
+  '> 본 문서는 에이전트 최상위 지침이다. 세션 시작 시 자동 로드된다.',
+  '> 사람용 도메인 설명은 `.project/PROJECT.md`, 진입 가이드는 `.project/AGENT-GUIDE.md` 참조.',
+  '> 앱을 띄워 사용자가 직접 확인해야 하는 프로젝트에만 해당한다. 아니면 이 절 전체를 삭제한다.',
+  '> 위 4 항목 중 *프로젝트에 해당 없는 것*은 행 자체 삭제. 빈 백틱(\\`\\`)은 사용 금지.',
+  '> 위 항목 중 *프로젝트에 해당 없는 것*은 행 자체 삭제. 빈 백틱(\\`\\`)은 사용 금지.',
+  '> 위 항목 중 *프로젝트에 해당 없는 것*은 행 자체 삭제. 빈 백틱(``)은 사용 금지.',
+  '> 이 파일은 Codex 세션이 *매 세션 시작 시 자동 로드*하는 단일 진입점이다.',
+  '> 이 파일은 메인 세션이 *매 세션 시작 시 자동 로드*하는 단일 진입점이다.',
+  '> 이전 `pre-commit-verify.sh` hook은 폐기 — task-close Step 2 게이트 + git-guard 안전망으로 충분 (redundant 검증 사이클 제거). 폐기 사유는 [plan/HOOKS.md](../plan/HOOKS.md) §5 참조.',
+  '> 프로젝트 메타 + 검증 명령 + 룰 참조 + 스킬 8종 + 동기화 룰만 포함한다.',
+  '> 프로젝트 메타 + 검증 명령 + 룰 참조 + 스킬 9종 + 동기화 룰만 포함한다.',
+  '> 프로젝트 메타 + 검증/테스트/검수 명령 + 룰 참조 + 스킬 9종 + 동기화 룰만 포함한다.',
+];
+
+module.exports = { LEGACY_TEMPLATE_QUOTES };

package/bin/lib.js

@@ -139,6 +139,12 @@ function sha256(filePath) {
   return 'sha256:' + crypto.createHash('sha256').update(buf).digest('hex');
 }
 
+// 파일이 아니라 *써 넣을 내용*의 해시. 조립해서 설치하는 자산(AGENTS.md)은 템플릿 원본과
+// 내용이 다르므로, manifest에는 반드시 조립 결과물의 해시를 기록해야 한다.
+function sha256Text(text) {
+  return 'sha256:' + crypto.createHash('sha256').update(Buffer.from(text, 'utf8')).digest('hex');
+}
+
 function walkTemplate(templateDir) {
   // template/ 안 모든 파일 상대경로 + 해시 맵 리턴
   // 결과: { 'CLAUDE.md': 'sha256:...', '.claude/skills/task-init/SKILL.md': 'sha256:...', ... }
@@ -1007,10 +1013,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;
@@ -1022,15 +1040,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;
@@ -1149,10 +1175,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) {
@@ -1172,6 +1304,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) {
@@ -1188,6 +1327,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) {
@@ -1254,6 +1402,7 @@ async function closeTask(mainWtPath, { taskNum }, opts = {}) {
     docPath: resolved.file,
     commits,
     aheadOfParent: aheadFinal,
+    changelog,
   };
   // 매핑 폴백 적용 내역 노출 — 코드가 자동 편입한 걸 스킬·사용자가 볼 수 있게
   if (split.multiPhase) prepResult.multiPhase = split.multiPhase;
@@ -1275,6 +1424,7 @@ module.exports = {
   gitignorePatternsFor,
   findTemplateDir,
   sha256,
+  sha256Text,
   walkTemplate,
   mkdirp,
   copyFile,
@@ -1329,5 +1479,7 @@ module.exports = {
   // task close 결정적 준비 (D1·D2)
   TAG_OF,
   splitUncommittedByPhase,
+  appendChangelogEntry,
+  checkDocsGate,
   closeTask,
 };