@seanyao/roll 0.5.0 → 2.602.1

package/lib/backfill-pi-usage.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+backfill-pi-usage — one-time, idempotent recovery of pi/deepseek token+cost
+into an existing loop events file.
+
+Why this exists
+---------------
+Before US-LOOP-026 the loop ran pi via ``pi -p`` (text mode), which prints no
+usage. loop-fmt's old passthrough still appended a ``stage=="usage"`` event on
+every retry attempt, each with ``model=="pi"`` and null tokens — so a single
+cycle accumulated up to ~180 empty usage events. The dashboard SUMS token
+fields across same-label usage events; with all-null tokens the SUM was 0
+(harmless), but it means every affected cycle shows ``—/—``.
+
+pi persists every session to ``~/.pi/agent/sessions/<enc-cwd>/<ts>_<uuid>.jsonl``
+with real per-message usage. This script recovers that, and rewrites the events
+file so each affected cycle is left with **exactly one** authoritative usage
+event (real tokens, cost frozen in native CNY) — collapsing the N null events to
+avoid the dashboard ×N inflation.
+
+Safety / idempotency
+--------------------
+- Backs up the events file to ``<file>.bak-<UTC>`` first; aborts if backup fails.
+- Only touches labels whose usage events are all pi-vendor (``model`` in
+  {"pi", "deepseek-v4-pro"}) AND carry null tokens AND match a pi session.
+  claude cycles, already-real cycles, and unmatched-null cycles are passed
+  through untouched.
+- Re-runnable: once a label has a real-token usage event it is no longer a
+  candidate, so a second run is a no-op.
+- FIX-065 tripwire: refuses to rewrite a production ``~/.shared/roll`` events
+  file from a test context (BATS / temp cwd) unless HOME itself is sandboxed.
+
+Usage
+-----
+    python3 lib/backfill-pi-usage.py --slug roll-ecf079
+    python3 lib/backfill-pi-usage.py --events /path/to/events.ndjson --dry-run
+"""
+
+import argparse
+import importlib.util
+import json
+import os
+import shutil
+import sys
+from datetime import datetime, timezone
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+
+PI_VENDOR_MODELS = ("pi", "deepseek-v4-pro")
+
+
+def _load_pi_emit():
+    spec = importlib.util.spec_from_file_location(
+        "pi_emit", os.path.join(_THIS_DIR, "agent_usage", "pi_emit.py")
+    )
+    m = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(m)
+    return m
+
+
+def _default_events_path(slug, shared=None):
+    base = shared or os.environ.get("LOOP_SHARED_ROOT") \
+        or os.path.expanduser("~/.shared/roll")
+    return os.path.join(base, "loop", "events-%s.ndjson" % slug)
+
+
+def _is_test_context():
+    return bool(os.environ.get("BATS_TEST_FILENAME")) or _cwd_is_temp()
+
+
+def _cwd_is_temp():
+    p = os.environ.get("PWD") or os.getcwd()
+    return any(seg in p for seg in ("/tmp/", "/private/tmp/", "/var/folders/", "/tmp."))
+
+
+def _home_is_sandbox():
+    home = os.environ.get("HOME") or ""
+    return any(seg in home for seg in ("/tmp/", "/private/tmp/", "/var/folders/", "/tmp."))
+
+
+def _tripwire(evfile):
+    """FIX-065: refuse a prod write from a test context."""
+    home = os.environ.get("HOME") or ""
+    if not home or _home_is_sandbox():
+        return
+    prod = os.path.join(home, ".shared", "roll") + os.sep
+    if os.path.abspath(evfile).startswith(os.path.abspath(prod)) and _is_test_context():
+        raise SystemExit(
+            "[FIX-065] refusing to rewrite prod events file from test context: %s" % evfile
+        )
+
+
+def _scan(lines):
+    """Parse lines → (events_or_None list, per-label usage summary).
+
+    Returns (parsed, labels) where parsed is a list of (raw_line, obj_or_None)
+    preserving order, and labels maps label → {"pi": bool, "real": bool}.
+    """
+    parsed = []
+    labels = {}
+    for raw in lines:
+        obj = None
+        try:
+            obj = json.loads(raw)
+        except (ValueError, TypeError):
+            obj = None
+        parsed.append((raw, obj))
+        if not obj or obj.get("stage") != "usage":
+            continue
+        lab = obj.get("label")
+        d = obj.get("detail") or {}
+        rec = labels.setdefault(lab, {"pi": False, "real": False})
+        if d.get("model") in PI_VENDOR_MODELS:
+            rec["pi"] = True
+        if d.get("input_tokens"):
+            rec["real"] = True
+    return parsed, labels
+
+
+def backfill(evfile, slug=None, shared=None, base_dir=None, dry_run=False):
+    """Rewrite evfile so each recoverable pi cycle nets one real usage event.
+
+    Returns a stats dict.
+    """
+    _tripwire(evfile)
+    pi_emit = _load_pi_emit()
+
+    with open(evfile) as f:
+        lines = f.readlines()
+
+    parsed, labels = _scan(lines)
+
+    # Candidate = pi-vendor, all-null, and a session match yields real usage.
+    candidates = [l for l, r in labels.items() if r["pi"] and not r["real"]]
+    replacement = {}  # label -> detail payload
+    matched, unmatched = [], []
+    for lab in candidates:
+        cwd = os.path.join(
+            (shared or os.environ.get("LOOP_SHARED_ROOT")
+             or os.path.expanduser("~/.shared/roll")),
+            "worktrees", "%s-cycle-%s" % (slug, lab),
+        )
+        ev = pi_emit.build_event(cwd=cwd, cycle_id=lab, slug=slug, base_dir=base_dir)
+        if ev is None:
+            unmatched.append(lab)
+            continue
+        replacement[lab] = ev["detail"]
+        matched.append(lab)
+
+    if dry_run or not matched:
+        # Nothing recoverable to rewrite → no backup, no write (keeps re-runs
+        # a true no-op instead of spawning empty .bak files).
+        return {
+            "candidates": len(candidates),
+            "matched": len(matched),
+            "unmatched": len(unmatched),
+            "matched_labels": sorted(matched),
+            "unmatched_labels": sorted(unmatched),
+            "written": False,
+        }
+
+    # Backup before any write; abort the whole run if backup fails.
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    bak = "%s.bak-%s" % (evfile, stamp)
+    shutil.copy2(evfile, bak)
+
+    # Stream rewrite: for an affected label, the FIRST usage line becomes the
+    # real event (original ts preserved so it stays in its day bucket), every
+    # subsequent same-label usage line is dropped → exactly one per label.
+    emitted = set()
+    out = []
+    for raw, obj in parsed:
+        if not obj or obj.get("stage") != "usage":
+            out.append(raw)
+            continue
+        lab = obj.get("label")
+        if lab not in replacement:
+            out.append(raw)  # claude / already-real / unmatched-null: untouched
+            continue
+        if lab in emitted:
+            continue  # collapse the remaining null duplicates away
+        new_ev = {
+            "ts": obj.get("ts"),
+            "stage": "usage",
+            "label": lab,
+            "detail": replacement[lab],
+            "outcome": "ok",
+        }
+        out.append(json.dumps(new_ev) + "\n")
+        emitted.add(lab)
+
+    tmp = evfile + ".tmp-%s" % stamp
+    with open(tmp, "w") as f:
+        f.writelines(out)
+    os.replace(tmp, evfile)
+
+    return {
+        "candidates": len(candidates),
+        "matched": len(matched),
+        "unmatched": len(unmatched),
+        "matched_labels": sorted(matched),
+        "unmatched_labels": sorted(unmatched),
+        "backup": bak,
+        "written": True,
+    }
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="backfill pi/deepseek usage into events file")
+    ap.add_argument("--slug", help="project slug (resolves default events path + session cwd)")
+    ap.add_argument("--events", help="explicit events file path (overrides --slug default)")
+    ap.add_argument("--shared", help="shared root (default ~/.shared/roll)")
+    ap.add_argument("--base-dir", help="pi sessions root override (tests)")
+    ap.add_argument("--dry-run", action="store_true", help="report only, write nothing")
+    args = ap.parse_args(argv)
+
+    evfile = args.events or _default_events_path(args.slug, args.shared)
+    if not os.path.isfile(evfile):
+        print("[backfill] no events file: %s" % evfile, file=sys.stderr)
+        return 1
+    if not args.slug:
+        # slug is needed to reconstruct session cwd; derive from filename.
+        base = os.path.basename(evfile)
+        if base.startswith("events-") and base.endswith(".ndjson"):
+            args.slug = base[len("events-"):-len(".ndjson")]
+
+    stats = backfill(
+        evfile, slug=args.slug, shared=args.shared,
+        base_dir=args.base_dir, dry_run=args.dry_run,
+    )
+    mode = "DRY-RUN" if args.dry_run else "WROTE"
+    print("[backfill] %s %s" % (mode, evfile))
+    print("  candidates=%d matched=%d unmatched=%d"
+          % (stats["candidates"], stats["matched"], stats["unmatched"]))
+    if stats.get("backup"):
+        print("  backup=%s" % stats["backup"])
+    if stats["unmatched_labels"]:
+        print("  unmatched (left as null): %s" % ", ".join(stats["unmatched_labels"]))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/changelog_audit.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""FIX-113: changelog audit — list PRs merged to main since the latest
+release tag that don't appear in CHANGELOG.md's ## Unreleased section.
+
+Run before `release.sh` so missing entries surface BEFORE the AI rewrite
+gets a chance to silently drop them.
+
+Usage:
+  python3 lib/changelog_audit.py                # report missing
+  python3 lib/changelog_audit.py --since v2026.520.1
+  python3 lib/changelog_audit.py --json         # machine-readable
+
+Exit 0 always (read-only audit). Output:
+  - "audit ok" + no missing list when CHANGELOG covers every merged PR
+  - "audit found N PR(s) without a CHANGELOG entry:" + list otherwise
+"""
+from __future__ import annotations
+import argparse, json, re, subprocess, sys
+from pathlib import Path
+
+PR_RE = re.compile(r"\(#(\d+)\)")
+SQUASH_RE = re.compile(r"^([a-z0-9]{7,40})\s+(.*?)\s*\(#(\d+)\)\s*$")
+
+# Heuristic: PR titles whose first token is one of these tags are usually
+# user-visible (need CHANGELOG entry). Tags like "chore:", "docs:" still
+# warrant a docs section entry; left to user judgement.
+USER_VISIBLE_PATTERNS = (
+    re.compile(r"\b(US-[A-Z0-9-]+-\d+)\b"),
+    re.compile(r"\b(FIX-\d+)\b"),
+    re.compile(r"\b(REFACTOR-\d+)\b"),
+)
+
+def _latest_tag() -> str:
+    """Return the most recent v* tag, or empty string if none."""
+    try:
+        out = subprocess.check_output(
+            ["git", "tag", "--list", "v*", "--sort=-creatordate"],
+            text=True, stderr=subprocess.DEVNULL,
+        ).strip()
+        for line in out.splitlines():
+            if line:
+                return line
+    except Exception:
+        pass
+    return ""
+
+def _merged_prs_since(since: str):
+    """Return list of (sha, subject, pr_number) for first-parent merges
+    on main between <since> and HEAD."""
+    cmd = ["git", "log", "--first-parent", "--oneline"]
+    if since:
+        cmd.append(f"{since}..HEAD")
+    try:
+        out = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL)
+    except Exception:
+        return []
+    rows = []
+    for line in out.splitlines():
+        m = SQUASH_RE.match(line)
+        if not m:
+            # Older "Merge pull request #N from <branch>" format
+            m2 = re.match(r"^([a-f0-9]{7,40})\s+Merge pull request #(\d+) from .*$", line)
+            if m2:
+                rows.append((m2.group(1), line.split(None, 1)[1], int(m2.group(2))))
+                continue
+            # Also look for parenthesized #N anywhere in subject
+            m3 = re.match(r"^([a-f0-9]{7,40})\s+(.*)$", line)
+            if m3:
+                pr_match = PR_RE.search(m3.group(2))
+                if pr_match:
+                    rows.append((m3.group(1), m3.group(2), int(pr_match.group(1))))
+            continue
+        rows.append((m.group(1), m.group(2), int(m.group(3))))
+    return rows
+
+def _read_unreleased_section(changelog: Path) -> str:
+    """Return the text of the ## Unreleased section (or empty string)."""
+    if not changelog.exists():
+        return ""
+    text = changelog.read_text(errors="ignore")
+    m = re.search(r"^## Unreleased\s*\n(.*?)(?=^## |\Z)", text, re.MULTILINE | re.DOTALL)
+    return m.group(1) if m else ""
+
+def _is_in_changelog(subject: str, unreleased_text: str) -> bool:
+    """A PR is considered covered if any story id from its subject appears in
+    the Unreleased section text."""
+    for pat in USER_VISIBLE_PATTERNS:
+        for m in pat.finditer(subject):
+            sid = m.group(1)
+            if sid in unreleased_text:
+                return True
+    # Fallback: PR number explicit mention
+    pr_m = PR_RE.search(subject)
+    if pr_m and f"#{pr_m.group(1)}" in unreleased_text:
+        return True
+    return False
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--since", default="", help="Compare against this tag (default: latest v* tag)")
+    ap.add_argument("--changelog", default="CHANGELOG.md")
+    ap.add_argument("--json", action="store_true", help="Machine-readable output")
+    args = ap.parse_args()
+
+    since = args.since or _latest_tag()
+    prs = _merged_prs_since(since)
+    cl = _read_unreleased_section(Path(args.changelog))
+
+    missing = []
+    skipped_internal = []
+    for sha, subject, pr_n in prs:
+        # Skip merges that are themselves releases
+        if subject.startswith("[release]") or subject.startswith("[ release]"):
+            continue
+        if _is_in_changelog(subject, cl):
+            continue
+        # Heuristic: subjects that don't contain a story id and start with
+        # internal-only tags (chore: backlog ..., chore: rebase, etc.) are
+        # marked as "internal", less likely to need user-facing entry.
+        is_user_visible = any(p.search(subject) for p in USER_VISIBLE_PATTERNS)
+        if is_user_visible:
+            missing.append({"pr": pr_n, "sha": sha, "subject": subject})
+        else:
+            skipped_internal.append({"pr": pr_n, "sha": sha, "subject": subject})
+
+    if args.json:
+        json.dump({
+            "since": since,
+            "total_prs": len(prs),
+            "missing_user_visible": missing,
+            "skipped_internal": skipped_internal,
+        }, sys.stdout, indent=2, ensure_ascii=False)
+        print()
+        return 0
+
+    print(f"changelog audit  since={since or '(no tag)'}  scanned {len(prs)} PR(s)")
+    print()
+    if not missing:
+        print(f"  ✓ audit ok — every user-visible PR is mentioned in CHANGELOG.md Unreleased")
+        if skipped_internal:
+            print(f"  · {len(skipped_internal)} internal/infra PR(s) skipped from audit")
+        return 0
+
+    print(f"  ⚠ {len(missing)} user-visible PR(s) without a CHANGELOG entry:")
+    for m in missing:
+        print(f"    #{m['pr']}  {m['subject']}")
+    print()
+    print("  Add bullets under '## Unreleased' in CHANGELOG.md before release,")
+    print("  or confirm these PRs are intentionally undocumented (rare).")
+    if skipped_internal:
+        print(f"  ({len(skipped_internal)} internal PR(s) skipped from audit)")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/changelog_generate.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""US-CL-006: changelog generate — deterministic draft generator.
+
+Extracts ✅ Done stories from .roll/backlog.md, filters internal entries,
+applies mechanical lint, and produces a draft ## Unreleased section.
+
+Usage:
+  python3 lib/changelog_generate.py           # output draft to stdout
+  python3 lib/changelog_generate.py --write   # append to CHANGELOG.md
+  python3 lib/changelog_generate.py --json    # machine-readable
+"""
+from __future__ import annotations
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# ─── Filters ─────────────────────────────────────────────────────────────────
+# Skip patterns: test infrastructure, internal contracts, dev-only changes.
+# These mirror the filter rules in $roll-.changelog SKILL.md Section 3.
+SKIP_PATTERNS = [
+    re.compile(r"test\s+infrastructure|bats\s|fixture|teardown|isolation|CI\s+时序", re.I),
+    re.compile(r"SKILL\.md|prompt\s+内部|schema\s+|contract\s+test|enum\s+强制", re.I),
+    re.compile(r"内部重构|提取函数|变量改名|目录调整|死代码|消重", re.I),
+    re.compile(r"发版脚本自身|release\.sh\s+逻辑|TCR\s+节奏|pre-commit|钩子", re.I),
+    re.compile(r"仅开发者|只开发者|维护者可见|内部可见", re.I),
+]
+
+# Category detection (best-effort keyword matching)
+CATEGORIES = [
+    ("新功能", [r"新增", r"添加", r"支持", r"新命令", r"新功能", r"引入", r"上线"]),
+    ("稳定性", [r"修复", r"崩溃", r"卡死", r"误报", r"泄漏", r"竞争", r"并发", r"死锁", r"幽灵"]),
+    ("可见性", [r"显示", r"dashboard", r"状态", r"可见", r"查看", r"实时", r"弹窗", r"日志"]),
+    ("自动化流水线", [r"PR\s", r"合并", r"auto-merge", r"loop\s", r"调度", r"launchd", r"定时"]),
+    ("工程和测试", [r"测试", r"CI\s", r"重构", r"提取", r"优化", r"提速", r"并行"]),
+]
+
+CATEGORY_ORDER = ["新功能", "稳定性", "可见性", "自动化流水线", "工程和测试", "其他"]
+
+# Changelog lint rules (inline copy of _changelog_lint_bullet for portability).
+LINT_BACKTICK_ID = re.compile(r"`[^`]*(_|\(\))[^`]*`")
+LINT_FILE_SUFFIX = re.compile(r"\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)")
+LINT_INTERNAL_WORD = re.compile(r"(Phase|Step)\s+[0-9]+|Helper|Schema|Fixture|Refactor")
+LINT_PATH_FRAG = re.compile(r"(^|[^A-Za-z0-9_])(\.roll|docs|bin|tests|scripts)/")
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+def _read_done_stories(backlog_path: Path) -> list[tuple[str, str, str]]:
+    """Extract ✅ Done rows from backlog table.
+
+    Returns list of (story_id, description, source_tag).
+    """
+    rows: list[tuple[str, str, str]] = []
+    text = backlog_path.read_text(encoding="utf-8")
+    for line in text.splitlines():
+        if not line.startswith("|") or line.count("|") < 4:
+            continue
+        if "✅ Done" not in line:
+            continue
+        parts = line.split("|")
+        if len(parts) < 4:
+            continue
+        # story id from first column
+        id_m = re.search(r"\[([A-Z]+-[A-Z0-9-]+-\d+|FIX-\d+|REFACTOR-\d+)\]", parts[1])
+        story_id = id_m.group(1) if id_m else ""
+        desc = parts[2].strip()
+        if not desc or desc.lower() == "description":
+            continue
+        # source tag: loop-executed stories get [loop]
+        source = "loop" if re.search(r"US-AUTO|US-LOOP|FIX-|REFACTOR-", story_id) else ""
+        rows.append((story_id, desc, source))
+    return rows
+
+
+def _is_internal(desc: str) -> bool:
+    for pat in SKIP_PATTERNS:
+        if pat.search(desc):
+            return True
+    return False
+
+
+def _clean_description(desc: str) -> str:
+    # Remove depends-on / manual-only tags
+    desc = re.sub(r"`?depends-on:[^`|]+`?", "", desc)
+    desc = re.sub(r"`?manual-only:[^`|]+`?", "", desc)
+    # Remove markdown links — keep link text only
+    desc = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", desc)
+    # Collapse whitespace
+    desc = re.sub(r"\s+", " ", desc).strip()
+    # Remove leading em-dash / hyphen noise
+    desc = re.sub(r"^[—\-]\s*", "", desc)
+    return desc
+
+
+def _detect_category(desc: str) -> str:
+    for cat, patterns in CATEGORIES:
+        for pat in patterns:
+            if re.search(pat, desc, re.I):
+                return cat
+    return "其他"
+
+
+def _already_in_changelog(story_id: str, desc: str, changelog_path: Path) -> bool:
+    if not changelog_path.exists():
+        return False
+    text = changelog_path.read_text(encoding="utf-8")
+    if story_id in text:
+        return True
+    # Also check by description text (cleaned, first 20 chars) to catch
+    # entries that don't carry the story ID.
+    desc_stub = desc[:20].strip()
+    if desc_stub and desc_stub in text:
+        return True
+    return False
+
+
+def _lint_bullet(bullet: str) -> list[str]:
+    """Return list of violation tags (empty = clean)."""
+    viols: list[str] = []
+    stripped = re.sub(r"`[^`]*`", "", bullet)
+    if LINT_BACKTICK_ID.search(bullet):
+        viols.append("backtick-identifier")
+    if LINT_FILE_SUFFIX.search(stripped):
+        viols.append("file-suffix")
+    if LINT_INTERNAL_WORD.search(bullet):
+        viols.append("internal-word")
+    # length: visible chars > 50
+    vis_len = len(stripped.strip())
+    if vis_len > 50:
+        viols.append("over-length")
+    if LINT_PATH_FRAG.search(stripped):
+        viols.append("path-fragment")
+    return viols
+
+
+def _format_bullet(desc: str, source: str) -> str:
+    tag = f" [{source}]" if source else ""
+    return f"- {desc}{tag}"
+
+
+def _build_draft(groups: dict[str, list[tuple[str, str, str]]]) -> str:
+    lines = ["## Unreleased", ""]
+    for cat in CATEGORY_ORDER:
+        if cat not in groups:
+            continue
+        lines.append(f"### {cat}")
+        lines.append("")
+        for _story_id, desc, source in groups[cat]:
+            bullet = _format_bullet(desc, source)
+            viols = _lint_bullet(bullet)
+            if viols:
+                bullet += f"  # lint: {', '.join(viols)}"
+            lines.append(bullet)
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _write_to_changelog(draft: str, changelog_path: Path) -> None:
+    """Merge draft into CHANGELOG.md, avoiding duplicates."""
+    if changelog_path.exists():
+        text = changelog_path.read_text(encoding="utf-8")
+    else:
+        text = "# Changelog\n\n"
+
+    if "## Unreleased" not in text:
+        # Insert right after the title
+        text = text.rstrip("\n") + "\n\n" + draft
+    else:
+        # Extract existing Unreleased section, merge new bullets
+        # Pattern: from ## Unreleased up to next ## or EOF
+        m = re.search(r"^(## Unreleased\s*\n)(.*?)(?=\n## |\Z)", text, re.MULTILINE | re.DOTALL)
+        if not m:
+            text = text.rstrip("\n") + "\n\n" + draft
+        else:
+            existing = m.group(2)
+            new_lines = draft.splitlines()[2:]  # drop "## Unreleased" and blank line
+            merged = existing.rstrip("\n") + "\n"
+            for line in new_lines:
+                # Skip category headers already present
+                if line.startswith("### ") and line in existing:
+                    continue
+                # Skip bullets already present
+                bullet_core = re.sub(r"\s*\[loop\]\s*$", "", line).strip()
+                if bullet_core and bullet_core not in existing:
+                    merged += line + "\n"
+            text = text[: m.start()] + "## Unreleased\n" + merged + text[m.end() :]
+
+    changelog_path.write_text(text, encoding="utf-8")
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Generate a draft ## Unreleased section from backlog ✅ Done stories."
+    )
+    ap.add_argument("--backlog", default=".roll/backlog.md", help="Path to backlog file")
+    ap.add_argument("--changelog", default="CHANGELOG.md", help="Path to CHANGELOG.md")
+    ap.add_argument("--write", action="store_true", help="Write draft to CHANGELOG.md")
+    ap.add_argument("--json", action="store_true", help="Machine-readable output")
+    args = ap.parse_args()
+
+    backlog = Path(args.backlog)
+    changelog = Path(args.changelog)
+
+    if not backlog.exists():
+        print("Error: backlog file not found", file=sys.stderr)
+        return 1
+
+    rows = _read_done_stories(backlog)
+
+    filtered: list[tuple[str, str, str, str]] = []
+    for story_id, desc, source in rows:
+        if _already_in_changelog(story_id, desc, changelog):
+            continue
+        if _is_internal(desc):
+            continue
+        cleaned = _clean_description(desc)
+        if not cleaned:
+            continue
+        cat = _detect_category(cleaned)
+        filtered.append((story_id, cleaned, source, cat))
+
+    if args.json:
+        json.dump(
+            {
+                "stories_found": len(rows),
+                "stories_drafted": len(filtered),
+                "draft": [
+                    {"id": sid, "desc": d, "category": c, "source": s}
+                    for sid, d, s, c in filtered
+                ],
+            },
+            sys.stdout,
+            indent=2,
+            ensure_ascii=False,
+        )
+        print()
+        return 0
+
+    if not filtered:
+        print("# No new ✅ Done stories found for CHANGELOG.")
+        return 0
+
+    groups: dict[str, list[tuple[str, str, str]]] = {}
+    for story_id, desc, source, cat in filtered:
+        groups.setdefault(cat, []).append((story_id, desc, source))
+
+    draft = _build_draft(groups)
+
+    if args.write:
+        _write_to_changelog(draft, changelog)
+        print(f"Updated {changelog}")
+    else:
+        print(draft, end="")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())