/cc-dev:zenhub:changelog [--since-tag  < tag > ] [--since-sprint current|next| < name > ] [--dry-run] [--out  < path > ]

// sprint window takes precedence over tag window
let windowStart, windowEnd = new Date().toISOString();
if (opts.sinceSprint) {
  const sprint = await resolveSprint(opts.sinceSprint); // see zenhub-conventions  " Sprint Selector Resolution " 
   if (!sprint) throw new Error(`스프린트  ' ${opts.sinceSprint} '   못 찾음 (current/next/ < name > ).`);
  windowStart = sprint.startAt;            // sprint 기간 = 윈도우
  windowEnd   = sprint.endAt ?? windowEnd;
} else {
  const tag = opts.sinceTag
    ?? (await Bash(`git describe --tags --abbrev=0`)).trim(); // 기본: 가장 최근 tag
  // tag 날짜 (release 우선, 없으면 git log)
  windowStart = (await Bash(
    `gh release view ${tag} --json createdAt -q .createdAt 2 > /dev/null `
    + `|| git log -1 --format=%cI ${tag}`
  )).trim();
}

// searchClosedIssues 는 close 검증에 쓰던 도구 — 여기선 윈도우 집계로 확장.
const raw = await mcp__zenhub__searchClosedIssues({ query:  " * "   });
const inWindow = raw.filter(i = > 
   i.closedAt  & &   i.closedAt  > = windowStart  & &   i.closedAt  < = windowEnd
);
// 정확 매칭이 필요하면 #N 은 번호로(부분 문자열 아님): i.number === n

const issueTypes = await mcp__zenhub__getIssueTypes();
// 타입/라벨 → 섹션 매핑 (커밋 prefix 대신 이슈 타입이 source of truth)
function sectionOf(issue) {
  const type = (issue.issueType?.name ??  " " ).toLowerCase();
  const labels = (issue.labels ?? []).map(l = >   l.name.toLowerCase());
  if (type ===  " feature "   || labels.includes( " feature " ) || labels.includes( " feat " )) return  " Added " ;
  if (type ===  " bug "       || labels.includes( " bug " )     || labels.includes( " fix " ))  return  " Fixed " ;
  if (type ===  " task "      || labels.includes( " chore " )   || labels.includes( " refactor " )) return  " Changed " ;
  if (labels.includes( " docs " ) || labels.includes( " documentation " )) return  " Docs " ;
  return  " Other " ;
}
const sections = { Added: [], Fixed: [], Changed: [], Docs: [], Other: [] };
for (const i of inWindow) sections[sectionOf(i)].push(i);

for (const i of inWindow) {
  // gh 로 이슈에 연결된 PR (timeline 의 cross-reference / closed-by)
  const prs = (await Bash(
    `gh issue view ${i.number} --json closedByPullRequestsReferences `
    + `-q  ' .closedByPullRequestsReferences[]?.url '   2 > /dev/null`
  )).trim().split( " \n " ).filter(Boolean);
  i._prLinks = prs; // 비면 PR 백링크 생략
}

const version = opts.sinceSprint ?? `since ${opts.sinceTag ??  " latest tag " }`;
const date = windowEnd.slice(0, 10);
let md = `## ${version} — ${date}\n\n`;
for (const [name, items] of Object.entries(sections)) {
  if (!items.length) continue;
  md += `### ${name}\n`;
  for (const i of items) {
    const pr = i._prLinks?.length ? ` (${i._prLinks.join( " ,  " )})` :  " " ;
    md += `- ${i.title} (#${i.number})${pr}\n`;
  }
  md +=  " \n " ;
}

if (opts.dryRun) {
  console.log(md);                      // 파일 안 쓰고 출력만
} else {
  const out = opts.out ??  " CHANGELOG.md " ;
  const prev = (await Bash(`cat ${out} 2 > /dev/null || true`));
  await Write(out, md + (prev ?  " \n "   + prev :  " " )); // 맨 위에 prepend
}

// 스프린트 해석 — zenhub-conventions  " Sprint Selector Resolution "   그대로 재사용 (재정의 금지)
async function resolveSprint(selector) {
  if (selector ===  " next " ) return await mcp__zenhub__getUpcomingSprint();
  if (!selector || selector ===  " current " ) return await mcp__zenhub__getSprint(); // 활성
  const { openSprints } = await mcp__zenhub__listRecentSprints();
  return openSprints.find(s = >   s.name.includes(String(selector)));
}

// 닫힌 이슈 집계 (윈도우 필터는 closedAt 으로)
const closed = await mcp__zenhub__searchClosedIssues({ query:  " * "   });

// 타입 분류용
const issueTypes = await mcp__zenhub__getIssueTypes();

// 단건 #N 확인이 필요하면 (getIssue 없음) searchLatestIssues 로 조회 후 number 정확 매칭
const hit = (await mcp__zenhub__searchLatestIssues({ query: `#${n}` }))
  .find(i = >   i.number === n);