@angar2/taskery 0.8.1 → 1.0.0

package/bin/check.js

@@ -0,0 +1,166 @@
+// approve-plan · test-code · test-scenario — 계획 끝 기록, 코드 테스트, 실사용 시나리오 결과(§5-3)
+const L = require('./lib');
+
+async function approvePlan(ctx, a) {
+  const main = ctx.main;
+  const num = L.parseTaskNum(a.task);
+  const st = L.readState(main, num);
+  if (st.closed) L.fail(`${L.taskLabel(num)}은 이미 닫혔다.`);
+  const text = L.readDoc(main, st);
+  const problems = [];
+  if (!L.goalLine(text)) problems.push('`## 목표`가 비어 있다');
+  const files = L.plannedFiles(text);
+  if (!files.length) problems.push('`## 만질 파일`(medium·large는 `## Phase`의 `- 파일:` 포함)에 파일이 없다 — 한 줄에 `- 경로` 하나씩');
+  if (L.sw(st, 'test')) {
+    const n = L.parseCriteria(text).length;
+    if (n < 1 || n > 5) {
+      problems.push(`\`## 완료 기준\` 시나리오가 ${n}개다 — 테스트 켜짐이면 1~5개를 \`1. [AUTO] 시작 → 행동 → 기대하는 끝 상태\` 형식으로 적는다`);
+    }
+  }
+  if (problems.length) L.fail(`approve-plan: ${L.taskLabel(num)} 태스크 문서를 고친 뒤 다시 부른다.\n${problems.map((p) => `- ${p}`).join('\n')}\n문서: ${L.docShown(main, st)}`);
+  st.approve = { at: L.nowIso(), files };
+  L.writeState(main, st);
+  L.syncDoc(main, st);
+  const d = L.stageDurations(st);
+  const next = L.sw(st, 'dev') ? '개발(task-dev)' : '테스트(task-test)';
+  return `${L.taskLabel(num)} 계획을 기록했다 — 시작·기획 ${L.minutes(d.plan)}, 만질 파일 ${files.length}개.\n다음: ${next}.`;
+}
+
+// 등록된 코드 테스트를 dir에서 차례로 실행한다. 실패하면 멈춤 오류를 던진다
+async function runCodeTests(main, dir) {
+  const manifest = L.requireInstalled(main);
+  const cmds = manifest.codeTest;
+  if (cmds === 'none') return { none: true, ms: 0, outputs: [] };
+  if (!Array.isArray(cmds) || cmds.length === 0) {
+    L.fail(
+      'test-code: 등록된 코드 테스트 명령이 없다. 리포를 보고 화면을 켜지 않는 코드 테스트 명령(린트·타입·빌드·단위 테스트)을 정해 ' +
+        "`test-code --register \"<명령>\" [\"<명령>\" …]`으로 등록한 뒤 다시 부른다. 코드 테스트가 없는 리포면 `test-code --register none`.",
+    );
+  }
+  let total = 0;
+  const outputs = [];
+  for (const cmd of cmds) {
+    const r = await L.runShell(cmd, dir);
+    total += r.ms;
+    if (r.code !== 0) {
+      L.fail(`test-code: 실패 — \`${cmd}\` (종료 코드 ${r.code})\n--- 출력 끝부분 ---\n${L.tail(r.out, 60)}\n---\n원인을 고친 뒤 다시 부른다.${overNotice(total, cmds)}`);
+    }
+    outputs.push({ cmd, out: r.out });
+  }
+  return { none: false, ms: total, outputs };
+}
+
+function overNotice(totalMs, cmds) {
+  if (totalMs <= L.CODE_TEST_NOTICE_MS) return '';
+  return (
+    `\n알림: 코드 테스트가 3분을 넘었다(${L.minutes(totalMs)}) — 화면을 켜는 테스트가 섞였는지 확인한다.\n` +
+    `지금 등록된 명령: ${cmds.map((c) => `\`${c}\``).join(', ')}\n` +
+    '바꾸려면 `test-code --register "<명령>" …`으로 목록 전체를 다시 등록한다.'
+  );
+}
+
+async function testCode(ctx, a) {
+  const main = ctx.main;
+  if (a.register) {
+    const list = a.register.map((s) => String(s).trim()).filter(Boolean);
+    if (!list.length) L.fail('test-code --register: 등록할 명령을 하나 이상 넣는다. 코드 테스트가 없는 리포면 `--register none`.');
+    const manifest = L.requireInstalled(main);
+    manifest.codeTest = list.length === 1 && list[0] === 'none' ? 'none' : list;
+    L.writeManifest(main, manifest);
+    return manifest.codeTest === 'none'
+      ? '코드 테스트 없음으로 등록했다 — test-code는 코드 지문만 남기고 통과한다.'
+      : `코드 테스트 명령 ${list.length}개를 등록했다(목록 전체를 바꿨다):\n${list.map((c) => `- ${c}`).join('\n')}`;
+  }
+  let st = null;
+  let dir;
+  if (a.task) {
+    st = L.readState(main, L.parseTaskNum(a.task));
+    if (st.closed) L.fail(`${L.taskLabel(st.num)}은 이미 닫혔다.`);
+    dir = L.workDir(main, st);
+  } else {
+    dir = L.git(ctx.cwd, ['rev-parse', '--show-toplevel']);
+  }
+  const result = await runCodeTests(main, dir);
+  const cmds = L.requireInstalled(main).codeTest;
+  const lines = [];
+  if (result.none) lines.push('코드 테스트 없음으로 등록된 리포 — 실행 없이 통과.');
+  else {
+    lines.push(`통과 — ${result.outputs.length}개 명령, ${L.minutes(result.ms)}.`);
+    for (const o of result.outputs) lines.push(`--- \`${o.cmd}\` 출력 끝부분 ---\n${L.tail(o.out, 15) || '(출력 없음)'}`);
+  }
+  if (st) {
+    st.testCode = { at: L.nowIso(), fingerprint: L.fingerprint(dir) };
+    L.writeState(main, st);
+    L.syncDoc(main, st);
+    lines.push(`${L.taskLabel(st.num)} 개발 칸을 기록했다 — 개발 ${L.minutes(L.stageDurations(st).dev)}.`);
+  }
+  if (!result.none) lines.push(overNotice(result.ms, cmds).trim());
+  return lines.filter(Boolean).join('\n');
+}
+
+const RESULTS = ['pass', 'fail', 'accept'];
+
+function lastEntry(st, n) {
+  const list = (st.scenarios && st.scenarios[n]) || [];
+  return list[list.length - 1] || null;
+}
+
+async function testScenario(ctx, a) {
+  const main = ctx.main;
+  const num = L.parseTaskNum(a.task);
+  const st = L.readState(main, num);
+  if (st.closed) L.fail(`${L.taskLabel(num)}은 이미 닫혔다.`);
+  const criteria = L.parseCriteria(L.readDoc(main, st));
+  const n = parseInt(a.number, 10);
+  if (!criteria.length) L.fail('test-scenario: 태스크 문서 `## 완료 기준`에 시나리오가 없다.');
+  if (!(n >= 1 && n <= criteria.length)) L.fail(`test-scenario: 시나리오 번호는 1~${criteria.length} 중 하나다 (받음: '${a.number}').`);
+  const result = String(a.result || '').toLowerCase();
+  if (!RESULTS.includes(result)) L.fail("test-scenario: 결과는 pass · fail · accept 중 하나다.");
+  const text = String(a.text || '').trim();
+  if (!text) {
+    L.fail(
+      result === 'accept'
+        ? 'test-scenario accept: FAIL을 알고 넘어가자고 한 사용자의 말을 그대로 넣는다.'
+        : 'test-scenario: 증거(실행 출력, 화면 캡처 경로, 또는 사용자 확인 시각)를 넣는다. 증거 없는 PASS는 적지 않는다.',
+    );
+  }
+  if (result === 'accept') {
+    const last = lastEntry(st, n);
+    if (!last || last.result !== 'fail') L.fail(`test-scenario accept: 시나리오 ${n}의 마지막 결과가 FAIL일 때만 받는다.`);
+  }
+  const at = L.nowIso();
+  st.scenarios = st.scenarios || {};
+  st.scenarios[n] = st.scenarios[n] || [];
+  st.scenarios[n].push(result === 'accept' ? { result, quote: text, at } : { result, evidence: text, at });
+  const label = result === 'pass' ? 'PASS' : result === 'fail' ? 'FAIL' : 'FAIL 수락';
+  const body = result === 'accept' ? `사용자: "${text}"` : text;
+
+  // 모든 시나리오가 PASS거나 FAIL 뒤 accept면 테스트 칸을 채운다
+  let complete = true;
+  let accepted = false;
+  for (let i = 1; i <= criteria.length; i++) {
+    const last = lastEntry(st, i);
+    if (!last || last.result === 'fail') complete = false;
+    else if (last.result === 'accept') accepted = true;
+  }
+  if (complete) st.testDone = { at, accepted };
+  else delete st.testDone;
+  L.writeState(main, st);
+  L.appendResult(main, st, `- 시나리오 ${n} · ${label} · ${body} · ${L.clock(at)}`);
+  L.syncDoc(main, st);
+
+  const out = [`${L.taskLabel(num)} 시나리오 ${n}: ${label} 기록.`];
+  if (complete) out.push(`모든 시나리오가 끝났다 — 테스트 칸을 채웠다(${L.minutes(L.stageDurations(st).test)}${accepted ? ', FAIL 수락' : ''}). 다음: 마무리(task-close).`);
+  else {
+    const left = [];
+    for (let i = 1; i <= criteria.length; i++) {
+      const last = lastEntry(st, i);
+      if (!last) left.push(`${i}(결과 없음)`);
+      else if (last.result === 'fail') left.push(`${i}(FAIL)`);
+    }
+    out.push(`남은 시나리오: ${left.join(', ')}`);
+  }
+  return out.join('\n');
+}
+
+module.exports = { approvePlan, testCode, testScenario, runCodeTests, lastEntry };

package/bin/commands.js

@@ -0,0 +1,151 @@
+// 명령 정의표 — 이름·받는 값·할 일을 한 번만 적고, CLI 입구(taskery.js)와 MCP 도구(mcp.js)를 여기서 만든다(§5-3)
+const L = require('./lib');
+const { prepareTask } = require('./prepare');
+const { approvePlan, testCode, testScenario } = require('./check');
+const { verifyClose, commitTask, mergeTask, closeTask } = require('./finish');
+const { status } = require('./status');
+const { planInit } = require('./plan');
+const { backlogAdd, backlogGet, backlogMark } = require('./backlog');
+const { prune } = require('./prune');
+const { orcaDispatchTask, reportTask, waitReports } = require('./orche');
+
+// 인자 종류: positional(순서대로) · string(--이름 값) · bool(--이름) · list(--이름 값 값 …)
+const TASK = { name: 'task', positional: true, desc: '태스크 번호 (TASK-012 또는 12)' };
+const RANGE = { name: 'range', desc: '사용자가 새로 말한 진행 범위 — 태스크 문서의 범위 메모만 바꾼다' };
+
+const COMMANDS = [
+  {
+    name: 'status',
+    summary: '열린 태스크·단계 표·단계별 시간·문서 경로·워크트리 경로, 플랜별 시작할 수 있는 태스크를 보여 준다',
+    args: [],
+    run: status,
+  },
+  {
+    name: 'plan-init',
+    summary: '다음 플랜 번호로 .taskery/plans/<NNN>_<slug>/PLAN.md 틀을 만든다',
+    args: [
+      { name: 'slug', positional: true, desc: '플랜 이름 — 영문 kebab-case (필수)' },
+      { name: 'title', desc: '플랜 제목 (없으면 slug)' },
+    ],
+    run: planInit,
+  },
+  {
+    name: 'prepare-task',
+    summary: '태스크를 연다 — 번호·브랜치·워크트리·태스크 문서·기록',
+    args: [
+      { name: 'name', positional: true, desc: '태스크 제목 한 줄 (필수)' },
+      { name: 'slug', desc: '영문 kebab-case — 브랜치·문서 파일 이름 (필수)' },
+      { name: 'type', desc: 'feature · bug · improve · refactor · docs · chore (필수)' },
+      { name: 'size', desc: 'small · medium · large (필수)' },
+      { name: 'switch', desc: '켜진 스위치 목록, 예 plan,dev,test (기본 모두 켜짐)' },
+      { name: 'range', desc: '사용자가 말한 진행 범위 그대로 (기본 한 단계)' },
+      { name: 'plan', desc: '플랜 폴더 이름 (플랜이 하나면 생략)' },
+      { name: 'item', desc: 'PLAN.md 태스크 목록의 항목 번호' },
+      { name: 'from', desc: '옮겨 오는 백로그 번호 목록, 예 BL-3,BL-7' },
+      { name: 'dev', desc: '작업자 식별자 (GIT_RULE.md 브랜치 이름에 작업자 칸이 있을 때 필수)' },
+      { name: 'no-worktree', type: 'bool', desc: '워크트리 생략 — 사용자가 명시했을 때만' },
+      { name: 'no-branch', type: 'bool', desc: '브랜치·워크트리 생략 — 사용자가 명시했을 때만' },
+    ],
+    run: prepareTask,
+  },
+  {
+    name: 'approve-plan',
+    summary: '태스크 문서(목표·만질 파일·완료 기준)를 검사하고 계획 끝을 기록한다',
+    args: [TASK, RANGE],
+    run: approvePlan,
+  },
+  {
+    name: 'test-code',
+    summary: '등록된 코드 테스트를 실행한다(태스크를 주면 개발 칸 기록). --register로 명령 목록을 등록·교체한다',
+    args: [
+      { ...TASK, desc: '태스크 번호 (없으면 기록 없이 결과만)' },
+      { name: 'register', type: 'list', desc: '코드 테스트 명령 목록 — 부를 때마다 목록 전체를 바꾼다. 없으면 none' },
+      RANGE,
+    ],
+    run: testCode,
+  },
+  {
+    name: 'test-scenario',
+    summary: '완료 기준 시나리오 결과를 기록한다 — pass|fail "증거" 또는 accept "<사용자가 한 말>"',
+    args: [
+      TASK,
+      { name: 'number', positional: true, desc: '시나리오 번호' },
+      { name: 'result', positional: true, desc: 'pass · fail · accept' },
+      { name: 'text', positional: true, desc: 'pass·fail은 증거, accept는 사용자가 한 말' },
+      RANGE,
+    ],
+    run: testScenario,
+  },
+  { name: 'verify-close', summary: '마무리 검사만 한다', args: [TASK, RANGE], run: verifyClose },
+  { name: 'commit-task', summary: 'Phase별 코드 커밋만 하고 병합 확인 요약을 낸다', args: [TASK, RANGE], run: commitTask },
+  { name: 'merge-task', summary: '병합 잠금 안에서 부모 최신으로 rebase한 뒤 병합한다', args: [TASK, RANGE], run: mergeTask },
+  { name: 'close-task', summary: '워크트리·브랜치를 정리하고 태스크를 닫는다(주인이 본진에서)', args: [TASK], run: closeTask },
+  {
+    name: 'prune',
+    summary: '닫힌 태스크에 남은 워크트리·브랜치를 정리한다 — 기본은 항목마다 묻는다',
+    args: [{ name: 'yes', type: 'bool', desc: '묻지 않고 정리 — 사용자가 명시했을 때만. 커밋 안 된 변경이 있는 곳은 건너뛴다' }],
+    interactive: true,
+    run: prune,
+  },
+  {
+    name: 'backlog-add',
+    summary: '백로그 번호를 발급해 BACKLOG.md 열린 항목 맨 위에 빈 양식을 넣는다',
+    args: [
+      { name: 'title', positional: true, desc: '항목 제목 한 줄 (필수)' },
+      { name: 'type', desc: 'bug · improve · feature · refactor · docs · chore' },
+    ],
+    run: backlogAdd,
+  },
+  {
+    name: 'backlog-get',
+    summary: '번호를 주면 그 항목 전문, 없으면 열린 항목 목록(번호·종류·제목·상태)',
+    args: [{ name: 'id', positional: true, desc: '백로그 번호 (BL-3 또는 3)' }],
+    run: backlogGet,
+  },
+  {
+    name: 'backlog-mark',
+    summary: '--from 없이 연 태스크를 백로그 항목에 연결한다(연결 태스크 칸·상태 진행)',
+    args: [
+      { name: 'id', positional: true, desc: '백로그 번호 (BL-3 또는 3)' },
+      { name: 'task', positional: true, desc: '태스크 번호 (TASK-012 또는 12)' },
+    ],
+    run: backlogMark,
+  },
+  {
+    name: 'orca-dispatch-task',
+    summary: 'Orca 새 탭에 태스크 세션을 띄우고 첫 지시문을 보낸다(Orca 전용). 탭 handle은 태스크 문서 메타에 기록한다',
+    args: [
+      TASK,
+      { name: 'agent', desc: 'claude · codex (필수)' },
+      { name: 'model', desc: '에이전트 모델 — 사용자가 정한 것 (필수)' },
+      { name: 'note', desc: '첫 지시문 끝에 붙일 오케스트레이션의 말 한 줄' },
+    ],
+    run: orcaDispatchTask,
+  },
+  {
+    name: 'report-task',
+    summary: '태스크 세션이 오케스트레이션에 보고 한 줄을 남긴다(.taskery/reports.log)',
+    args: [TASK, { name: 'text', positional: true, desc: '보고 한 줄 (필수)' }],
+    run: reportTask,
+  },
+  {
+    name: 'wait-reports',
+    summary: '안 읽은 보고가 생기면 그 줄들을 출력하고 끝난다. 보고 없이 10분이면 오래 조용한 태스크 탭 목록과 함께 끝난다(백그라운드 셸로 건다)',
+    args: [],
+    cliOnly: true,
+    run: waitReports,
+  },
+];
+
+// 명령 실행 공통 — 본진을 찾고, --range가 있으면 범위 메모를 먼저 갱신한다
+// ask는 묻는 명령(prune)에 CLI가 넘기는 질문 함수다. MCP에는 없다
+async function execute(cmd, args, { cwd = process.cwd(), main = null, ask = null } = {}) {
+  const ctx = { cwd, main: main || L.findMain(cwd), ask };
+  if (args.range && args.task && cmd.args.includes(RANGE)) {
+    const st = L.readState(ctx.main, L.parseTaskNum(args.task));
+    L.updateRange(ctx.main, st, String(args.range));
+  }
+  return cmd.run(ctx, args);
+}
+
+module.exports = { COMMANDS, execute };

package/bin/finish.js

@@ -0,0 +1,353 @@
+// verify-close · commit-task · merge-task · close-task — 마무리 4명령(검사·커밋·병합·정리, §5-3)
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const L = require('./lib');
+const { checkMain, installPackages, reseedBuildOutputs } = require('./prepare');
+const B = require('./backlog');
+const { runCodeTests, lastEntry } = require('./check');
+
+function openState(main, task) {
+  const num = L.parseTaskNum(task);
+  const st = L.readState(main, num);
+  if (st.closed) L.fail(`${L.taskLabel(num)}은 이미 닫혔다.`);
+  return st;
+}
+
+// 시작 커밋 이후 이 태스크의 코드 변경이 있나 — --no-branch는 작업 트리만 본다
+function hasCodeChange(main, st) {
+  const dir = L.workDir(main, st);
+  if (L.changedFiles(dir).length) return true;
+  if (st.noBranch) return false;
+  return parseInt(L.git(dir, ['rev-list', '--count', `${st.startCommit}..HEAD`]), 10) > 0;
+}
+
+async function verifyClose(ctx, a) {
+  const main = ctx.main;
+  const st = openState(main, a.task);
+  const dir = L.workDir(main, st);
+  const problems = [];
+  if (!st.approve) problems.push('계획 끝 표시가 없다 — 태스크 문서를 채우고 approve-plan을 부른다');
+  if (L.sw(st, 'dev')) {
+    if (!st.testCode) problems.push('test-code 통과 기록이 없다 — test-code를 부른다');
+    else if (L.fingerprint(dir) !== st.testCode.fingerprint) problems.push('test-code 통과 뒤 코드가 바뀌었다 — test-code를 다시 부른다');
+  } else if (hasCodeChange(main, st)) {
+    problems.push(
+      st.noBranch
+        ? '개발 꺼짐 태스크인데 작업 트리에 커밋 안 된 코드 변경이 있다 — 되돌리거나 스위치를 다시 정한다'
+        : '개발 꺼짐 태스크인데 시작 이후 코드 변경(커밋 또는 작업 트리)이 있다 — 되돌리거나 스위치를 다시 정한다',
+    );
+  }
+  if (L.sw(st, 'test')) {
+    const criteria = L.parseCriteria(L.readDoc(main, st));
+    if (!criteria.length) problems.push('`## 완료 기준`에 시나리오가 없다');
+    for (let i = 1; i <= criteria.length; i++) {
+      const last = lastEntry(st, i);
+      if (!last) problems.push(`시나리오 ${i}의 결과·증거가 없다 — test-scenario로 기록한다`);
+      else if (last.result === 'fail') problems.push(`시나리오 ${i}가 FAIL이다 — 고쳐서 다시 확인하거나, 사용자가 알고 넘어가기로 했으면 test-scenario … accept로 그 말을 기록한다`);
+    }
+  }
+  if (problems.length) L.fail(`verify-close: ${L.taskLabel(st.num)} 마무리 검사에 걸렸다.\n${problems.map((p) => `- ${p}`).join('\n')}`);
+  st.verify = { at: L.nowIso() };
+  L.writeState(main, st);
+  return `${L.taskLabel(st.num)} 마무리 검사 통과. 다음: commit-task.`;
+}
+
+// 바뀐 파일을 Phase별로 나눈다 — 여러 Phase면 앞 Phase, 목록에 없으면 마지막 Phase(§4-5)
+function groupByPhase(files, phases) {
+  const groups = phases.map(() => []);
+  const notes = {};
+  for (const f of files) {
+    const hits = phases.map((p, i) => (p.files.some((pf) => L.fileMatches(f, pf)) ? i : -1)).filter((i) => i >= 0);
+    if (hits.length === 0) groups[phases.length - 1].push(f);
+    else {
+      groups[hits[0]].push(f);
+      if (hits.length > 1) notes[f] = ` (Phase ${hits.map((i) => phases[i].num).join('·')} 변경 포함)`;
+    }
+  }
+  return { groups, notes };
+}
+
+function commitFiles(dir, files, message) {
+  L.git(dir, ['add', '-A', '--', ...files]);
+  L.git(dir, ['commit', '-q', '-m', message]);
+  return L.git(dir, ['rev-parse', 'HEAD']);
+}
+
+function commitBody(files, notes, reason) {
+  return `\n\n${files.map((f) => `- ${f}${notes[f] || ''}`).join('\n')}\n- 사유: ${reason}`;
+}
+
+async function commitTask(ctx, a) {
+  const main = ctx.main;
+  const st = openState(main, a.task);
+  if (!st.verify) L.fail(`commit-task: ${L.taskLabel(st.num)}의 마무리 검사 기록이 없다. verify-close를 먼저 부른다.`);
+  const dir = L.workDir(main, st);
+  const text = L.readDoc(main, st);
+  const rule = L.readGitRule(main);
+  const made = [];
+  if (L.sw(st, 'dev')) {
+    const files = L.changedFiles(dir);
+    if (files.length) {
+      const tag = L.TAG_OF[st.type] || 'docs';
+      const num = L.pad(st.num);
+      const phases = st.size === 'small' ? [] : L.parsePhases(text);
+      if (phases.length) {
+        const { groups, notes } = groupByPhase(files, phases);
+        phases.forEach((p, i) => {
+          if (!groups[i].length) return;
+          const summary = `Phase ${p.num} - ${p.name}`;
+          const msg = L.fillTemplate(rule.commit, { tag, num, summary }) + commitBody(groups[i], notes, p.reason || p.name);
+          made.push({ sha: commitFiles(dir, groups[i], msg), subject: msg.split('\n')[0], files: groups[i] });
+        });
+      } else {
+        const msg = L.fillTemplate(rule.commit, { tag, num, summary: st.title }) + commitBody(files, {}, L.goalLine(text) || st.title);
+        made.push({ sha: commitFiles(dir, files, msg), subject: msg.split('\n')[0], files });
+      }
+    }
+  }
+  const prev = (st.commit && st.commit.commits) || [];
+  const commits = [...prev, ...made];
+  const noCodeChange = !L.sw(st, 'dev') || (st.noBranch ? commits.length === 0 : !hasCodeChange(main, st));
+  st.commit = { at: L.nowIso(), noCodeChange, commits };
+  L.writeState(main, st);
+
+  // 병합 확인 화면 — 커밋 목록·바뀐 파일·단계별 시간·계획 확인 뒤 추가된 파일
+  let changed;
+  let list;
+  if (st.noBranch) {
+    list = commits.map((c) => `${c.sha.slice(0, 7)} ${c.subject}`);
+    changed = [...new Set(commits.flatMap((c) => c.files))];
+  } else {
+    const log = L.git(dir, ['log', '--format=%h %s', `${st.startCommit}..HEAD`]);
+    list = log ? log.split('\n') : [];
+    const diff = L.git(dir, ['diff', '--name-only', st.startCommit, 'HEAD']);
+    changed = diff ? diff.split('\n') : [];
+  }
+  const planned = (st.approve && st.approve.files) || [];
+  const added = changed.filter((f) => !planned.some((p) => L.fileMatches(f, p)));
+  const d = L.stageDurations(st);
+  const out = [`${L.taskLabel(st.num)} 「${st.title}」 커밋 요약`];
+  if (noCodeChange) out.push('- 코드 변경 없음 — 커밋하지 않았다. merge-task는 병합을 건너뛴다.');
+  else {
+    out.push(`- 커밋 ${list.length}개:`);
+    for (const l of list) out.push(`  - ${l}`);
+    out.push(`- 바뀐 파일 ${changed.length}개: ${changed.join(', ')}`);
+  }
+  out.push(
+    `- 단계별 시간: 시작·기획 ${L.minutes(d.plan) || '–'} · 개발 ${L.sw(st, 'dev') ? L.minutes(d.dev) || '–' : '꺼짐'} · 테스트 ${L.sw(st, 'test') ? L.minutes(d.test) || '–' : '꺼짐'}`,
+  );
+  out.push(`- 계획 확인 뒤 추가된 파일: ${added.length ? added.join(', ') : '없음'}`);
+  out.push('다음: merge-task (진행 범위가 "끝까지"가 아니면 사용자 확인을 받은 뒤).');
+  return out.join('\n');
+}
+
+function gitPath(dir, name) {
+  return L.git(dir, ['rev-parse', '--path-format=absolute', '--git-path', name]);
+}
+
+function rebaseInProgress(dir) {
+  return fs.existsSync(gitPath(dir, 'rebase-merge')) || fs.existsSync(gitPath(dir, 'rebase-apply'));
+}
+
+function unmergedFiles(dir) {
+  const out = L.git(dir, ['diff', '--name-only', '--diff-filter=U']);
+  return out ? out.split('\n') : [];
+}
+
+const MARKER_RE = /^(<{7}|>{7})( |$)/m;
+
+function conflictStop(st, files) {
+  return L.fail(
+    `merge-task: ${L.taskLabel(st.num)} rebase 중 충돌이 났다. 잠금은 풀었고 rebase 진행 상태는 그대로 두었다.\n` +
+      `충돌 파일:\n${files.map((f) => `- ${f}`).join('\n')}\n` +
+      '충돌 파일을 직접 읽고 고친 뒤 merge-task를 다시 부른다(스테이징·이어 가기는 명령이 한다). 풀지 못하면 멈추고 보고한다.',
+  );
+}
+
+// 부모 최신 위로 rebase — 진행 중인 rebase가 있으면 이어 가고, 부모가 움직였으면 다시 한다
+function rebaseOntoParent(dir, st) {
+  const env = { GIT_EDITOR: 'true' };
+  for (let guard = 0; guard < 100; guard++) {
+    if (rebaseInProgress(dir)) {
+      const unmerged = unmergedFiles(dir);
+      const marked = unmerged.filter((f) => {
+        const p = path.join(dir, f);
+        return fs.existsSync(p) && MARKER_RE.test(fs.readFileSync(p, 'utf8'));
+      });
+      if (marked.length) conflictStop(st, marked);
+      L.git(dir, ['add', '-A']);
+      if (L.git(dir, ['-c', 'core.editor=true', 'rebase', '--continue'], { env, allowFail: true }) === null) {
+        if (rebaseInProgress(dir) && unmergedFiles(dir).length) conflictStop(st, unmergedFiles(dir));
+        if (rebaseInProgress(dir)) L.fail('merge-task: rebase를 이어 가지 못했다. `git status`로 상태를 확인한다.');
+      }
+      continue;
+    }
+    if (L.isAncestor(dir, st.parent, 'HEAD')) return;
+    if (L.git(dir, ['rebase', st.parent], { env, allowFail: true }) === null) {
+      if (rebaseInProgress(dir)) conflictStop(st, unmergedFiles(dir));
+      L.fail('merge-task: rebase에 실패했다. `git status`로 상태를 확인한다.');
+    }
+  }
+  return L.fail('merge-task: rebase가 끝나지 않는다. `git status`로 상태를 확인한다.');
+}
+
+async function mergeTask(ctx, a) {
+  const main = ctx.main;
+  const st = openState(main, a.task);
+  if (!st.commit) L.fail(`merge-task: ${L.taskLabel(st.num)}의 커밋 기록이 없다. commit-task를 먼저 부른다.`);
+  if (st.merge && st.merge.commit) return `${L.taskLabel(st.num)}은 이미 병합했다 (${st.merge.commit.slice(0, 7)}).`;
+
+  if (L.needsNoMerge(st)) {
+    let note = '';
+    if (st.noWorktree && L.currentBranch(main) !== st.parent) {
+      L.git(main, ['checkout', st.parent]);
+      note = ` 본진을 부모 브랜치 ${st.parent}로 되돌렸다.`;
+    }
+    const why = !L.sw(st, 'dev') ? '개발 꺼짐' : st.noBranch ? '브랜치 생략' : '코드 변경 없음';
+    st.merge = { at: L.nowIso(), skipped: why };
+    L.writeState(main, st);
+    return `${L.taskLabel(st.num)} 병합을 건너뛴다(${why}).${note}\n다음: 태스크를 연 주인이 본진에서 close-task를 부른다.`;
+  }
+
+  if (!st.mergeStart) {
+    st.mergeStart = L.nowIso();
+    // rebase 전 브랜치 끝 — 부모에서 받아 온 변경에 의존성 파일이 있는지 볼 때 쓴다(충돌 뒤 다시 불러도 같은 값)
+    st.mergeFrom = L.git(st.noWorktree ? main : st.worktree, ['rev-parse', 'HEAD']);
+    L.writeState(main, st);
+  }
+  const rule = L.readGitRule(main);
+  return L.withLock(main, 'merge', async () => {
+    checkMain(main, { self: st, parent: st.parent });
+    const dir = st.noWorktree ? main : st.worktree;
+    rebaseOntoParent(dir, st);
+    const notes = [];
+    // 새 커밋이 들어와 코드가 test-code 때와 달라졌을 때만 코드 테스트를 다시 돌린다
+    const fp = L.fingerprint(dir);
+    if (st.testCode && fp !== st.testCode.fingerprint) {
+      // 의존성 파일(package-lock.json)이 바뀌었으면 다시 설치한 뒤 테스트한다
+      if (st.mergeFrom && L.git(dir, ['diff', '--name-only', st.mergeFrom, 'HEAD', '--', 'package-lock.json'])) {
+        for (const n of await installPackages(dir)) notes.push(`의존성 파일이 바뀌어 다시 설치했다: ${n}`);
+      }
+      const r = await runCodeTests(main, dir);
+      st.testCode.fingerprint = fp;
+      L.writeState(main, st);
+      notes.push(r.none ? '부모의 새 커밋을 받았다 — 코드 테스트 없음으로 등록된 리포.' : `부모의 새 커밋을 받아 코드 테스트를 다시 돌렸다 — 통과(${L.minutes(r.ms)}).`);
+    }
+    if (st.noWorktree) L.git(main, ['checkout', st.parent]);
+    const args = rule.merge === 'ff-only' ? ['merge', '--ff-only', st.branch] : ['merge', '--no-ff', '--no-edit', st.branch];
+    L.git(main, args);
+    const head = L.git(main, ['rev-parse', 'HEAD']);
+    st.merge = { at: L.nowIso(), commit: head };
+    L.writeState(main, st);
+    return [
+      `${L.taskLabel(st.num)}을 ${st.parent}에 병합했다(${rule.merge}, ${head.slice(0, 7)}).`,
+      ...notes,
+      '다음: 태스크를 연 주인이 본진에서 close-task를 부른다(직접 수행이면 워크트리에서 나와서).',
+    ].join('\n');
+  });
+}
+
+// CHANGELOG_RULE.md의 "항목 틀" 코드 블록을 읽어 변경 기록 한 항목을 쓴다
+function changelogTemplate(main) {
+  const file = path.join(main, '.taskery', 'rules', 'CHANGELOG_RULE.md');
+  const fallback = '## [TASK-{num}] {title}\n\n- 날짜: {date}\n- 유형: {type}\n- 요약: {goal}';
+  if (!fs.existsSync(file)) return fallback;
+  const m = fs.readFileSync(file, 'utf8').match(/## 항목 틀[\s\S]*?```(?:markdown)?\n([\s\S]*?)```/);
+  return m ? m[1].replace(/\s+$/, '') : fallback;
+}
+
+function writeChangelog(main, st, goal) {
+  const date = L.todayLocal();
+  const entry = L.fillTemplate(changelogTemplate(main), { num: L.pad(st.num), title: st.title, date, type: st.type, goal });
+  const file = path.join(main, '.taskery', 'changelog', `${date.slice(0, 7)}.md`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, `# 변경 기록 ${date.slice(0, 7)}\n\n${entry}\n`);
+  } else {
+    const lines = fs.readFileSync(file, 'utf8').split('\n');
+    const first = lines.findIndex((l) => /^## /.test(l));
+    if (first === -1) lines.push('', entry, '');
+    else lines.splice(first, 0, entry, '');
+    fs.writeFileSync(file, lines.join('\n'));
+  }
+  return file;
+}
+
+// 워크트리·브랜치 정리 — 커밋 안 된 변경이 있으면 남기고, 브랜치는 병합된 것만 지운다.
+// force는 prune에서 사용자가 확인했을 때만 — 병합 안 된 브랜치도 지운다(복구 명령 출력)
+function cleanup(main, st, { force = false } = {}) {
+  const notes = [];
+  if (st.noBranch) return notes;
+  const exists = L.branchExists(main, st.branch);
+  const tip = exists ? L.git(main, ['rev-parse', st.branch]) : null;
+  const merged = exists && L.isAncestor(main, st.branch, st.parent);
+  let branchFree = true;
+
+  if (st.worktree && fs.existsSync(st.worktree)) {
+    const dirty = L.changedFiles(st.worktree);
+    if (dirty.length) {
+      notes.push(`워크트리에 커밋 안 된 변경·추적 안 되는 파일이 있어 워크트리와 브랜치를 남겼다: ${st.worktree} (${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ' …' : ''})`);
+      return notes;
+    }
+    if (st.by === 'orca') {
+      // Orca는 병합을 증명할 수 없는 브랜치를 남긴다(`orca worktree rm --help`) — 병합 여부와 무관하게 부른다
+      try {
+        execFileSync('orca', ['worktree', 'rm', '--worktree', `path:${st.worktree}`, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        notes.push(`Orca 워크트리를 지웠다: ${st.worktree}`);
+      } catch (e) {
+        notes.push(`Orca 워크트리를 지우지 못해 남겼다: ${((e.stderr || '') + '').trim() || e.message}`);
+        branchFree = false;
+      }
+    } else if (L.git(main, ['worktree', 'remove', st.worktree], { allowFail: true }) === null) {
+      notes.push(`워크트리를 지우지 못해 남겼다: ${st.worktree}`);
+      branchFree = false;
+    } else {
+      notes.push(`워크트리를 지웠다: ${st.worktree}`);
+    }
+  }
+
+  if (!L.branchExists(main, st.branch)) {
+    if (exists) notes.push(`브랜치 ${st.branch}가 지워졌다. 복구: git branch ${st.branch} ${tip}`);
+    return notes;
+  }
+  if (!merged && !force) notes.push(`브랜치 ${st.branch}는 부모에 병합되지 않아 남겼다.`);
+  else if (!branchFree || L.currentBranch(main) === st.branch) notes.push(`브랜치 ${st.branch}를 지우지 못해 남겼다(사용 중).`);
+  else if (L.git(main, ['branch', merged ? '-d' : '-D', st.branch], { allowFail: true }) === null) notes.push(`브랜치 ${st.branch}를 지우지 못해 남겼다.`);
+  else notes.push(`브랜치 ${st.branch}를 지웠다. 복구: git branch ${st.branch} ${tip}`);
+  return notes;
+}
+
+async function closeTask(ctx, a) {
+  const main = ctx.main;
+  const st = openState(main, a.task);
+  const finished = L.hasFinishRecord(st);
+  const notes = [];
+  // 끝난 태스크면 워크트리를 지우기 직전에 빌드 결과 폴더를 본진의 씨앗으로(§7). 남길 워크트리(커밋 안 된 변경)는 그대로 둔다
+  if (finished && st.worktree && fs.existsSync(st.worktree) && !L.changedFiles(st.worktree).length) {
+    notes.push(...reseedBuildOutputs(main, st.worktree, L.readManifest(main).buildOutput));
+  }
+  notes.push(...cleanup(main, st));
+  const goal = L.goalLine(fs.existsSync(L.docAbs(main, st)) ? L.readDoc(main, st) : '') || st.title;
+  st.closed = { at: L.nowIso(), finished };
+  L.writeState(main, st);
+  L.syncDoc(main, st);
+  // 백로그 연결 표시 — (완료)·(포기), 연결 태스크가 모두 닫히면 항목 이동(§5-3)
+  const blNotes = await L.withLock(main, 'number', async () => B.markClosed(main, L.taskLabel(st.num), finished));
+  for (const n of blNotes) notes.push(`백로그: ${n}`);
+  if (finished) notes.push(`변경 기록: ${writeChangelog(main, st, goal)}`);
+  const d = L.stageDurations(st);
+  const row = (label, on, v) => `  - ${label}: ${on ? L.minutes(v) || '–' : '꺼짐'}`;
+  return [
+    `${L.taskLabel(st.num)} 「${st.title}」을 닫았다 — ${finished ? '끝난 태스크' : '포기(마무리 기록 없이 닫음)'}.`,
+    ...notes.map((n) => `- ${n}`),
+    '- 단계별 시간:',
+    row('시작·기획', true, d.plan),
+    row('개발', L.sw(st, 'dev'), d.dev),
+    row('테스트', L.sw(st, 'test'), d.test),
+    row('닫기', true, d.close),
+    `  - 합계: ${L.minutes(d.total)} (계획 확인·눈 확인·질문 답을 기다린 시간 포함, 병합 확인 대기는 뺌)`,
+  ].join('\n');
+}
+
+module.exports = { verifyClose, commitTask, mergeTask, closeTask, cleanup };