@seanyao/roll 2.602.5 → 2.604.1

package/lib/README.md

@@ -24,7 +24,6 @@ Python scripts and shell libraries that `bin/roll` delegates to for rendering-he
 | `loop-fmt.py` | Loop log formatter (ANSI-strip, timestamp alignment) |
 | `loop_unstick.py` | Diagnostic: detects and unsticks hung loop state |
 | `backfill-pi-usage.py` | Backfills pi/deepseek token and cost data into existing cycle records |
-| `changelog_audit.py` | Audits CHANGELOG.md against backlog entries |
 | `i18n.sh` | Shell wrapper that delegates i18n string lookups to `lib/i18n/` |
 | `slides-render.py` | Renders `.deck.md` → HTML slides |
 | `slides-validate.py` | Validates deck file syntax and asset references |

package/lib/changelog_audit.py

@@ -1,155 +1,149 @@
 #!/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.
+"""Changelog audit module (US-CONSIST-002).
 
-Run before `release.sh` so missing entries surface BEFORE the AI rewrite
-gets a chance to silently drop them.
+Checks that ✅ Done backlog stories are reflected in CHANGELOG.md.
+Provides both coverage checking and gap reporting.
 
-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
+Usage as library:
+  from lib.changelog_audit import check_changelog_coverage
+  result = check_changelog_coverage(done_stories, changelog_path)
 """
+
 from __future__ import annotations
-import argparse, json, re, subprocess, sys
+
 from pathlib import Path
+from typing import Any
 
-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():
+def _read_changelog_text(changelog_path: Path) -> str:
+    """Read changelog text, returning empty string if file is missing."""
+    if not changelog_path.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]"):
+    return changelog_path.read_text(encoding="utf-8")
+
+
+def check_changelog_coverage(
+    done_stories: dict[str, list[str]],
+    changelog_path: Path,
+) -> dict[str, Any]:
+    """Check that Done stories appear in CHANGELOG.md.
+
+    Args:
+        done_stories: {feature_name: [story_id, ...]} from backlog
+        changelog_path: Path to CHANGELOG.md
+
+    Returns:
+        {"status": "pass"|"fail", "gaps": [descriptions...]}
+    """
+    if not changelog_path.exists():
+        return {"status": "pass", "gaps": []}
+
+    changelog_text = _read_changelog_text(changelog_path)
+    gaps: list[str] = []
+
+    for feature_name, story_ids in done_stories.items():
+        for story_id in story_ids:
+            if story_id not in changelog_text:
+                gaps.append(
+                    f"Story '{story_id}' (feature '{feature_name}') is Done "
+                    "but not referenced in CHANGELOG.md"
+                )
+
+    return {
+        "status": "pass" if not gaps else "fail",
+        "gaps": gaps,
+    }
+
+
+def check_features_md_coverage(
+    done_features: dict[str, list[str]],
+    features_md_path: Path,
+) -> dict[str, Any]:
+    """Check that features with Done stories are listed in features.md.
+
+    Args:
+        done_features: {feature_name: [story_id, ...]} from backlog
+        features_md_path: Path to .roll/features.md
+
+    Returns:
+        {"status": "pass"|"fail", "gaps": [descriptions...]}
+    """
+    import re
+
+    if not features_md_path.exists():
+        return {"status": "pass", "gaps": []}
+
+    features_text = features_md_path.read_text(encoding="utf-8")
+    gaps: list[str] = []
+
+    for feature_name in done_features:
+        escaped = re.escape(feature_name)
+        if not re.search(r"(^|[\s/])" + escaped + r"([\s/).]|$)", features_text):
+            gaps.append(
+                f"Feature '{feature_name}' has Done stories but is missing "
+                "from features.md catalog"
+            )
+
+    return {
+        "status": "pass" if not gaps else "fail",
+        "gaps": gaps,
+    }
+
+
+def check_guide_doc_coverage(
+    done_features: dict[str, list[str]],
+    guide_en_dir: Path,
+) -> dict[str, Any]:
+    """Check that features with Done stories have guide documentation.
+
+    Heuristic: checks whether a .md file in guide/en/ references the feature
+    name or its story IDs.
+
+    Args:
+        done_features: {feature_name: [story_id, ...]} from backlog
+        guide_en_dir: Path to guide/en/
+
+    Returns:
+        {"status": "pass"|"fail", "gaps": [descriptions...]}
+    """
+    if not guide_en_dir.exists() or not guide_en_dir.is_dir():
+        return {"status": "pass", "gaps": []}
+
+    # Collect all guide text
+    all_guide_text = ""
+    for md_file in sorted(guide_en_dir.glob("*.md")):
+        try:
+            all_guide_text += md_file.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
             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())
+
+    # Also read practices/ subdirectory
+    practices_dir = guide_en_dir / "practices"
+    if practices_dir.exists() and practices_dir.is_dir():
+        for md_file in sorted(practices_dir.glob("*.md")):
+            try:
+                all_guide_text += md_file.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+
+    gaps: list[str] = []
+    for feature_name, story_ids in done_features.items():
+        found = False
+        # Check if feature name appears in guide text
+        if feature_name.lower() in all_guide_text.lower():
+            found = True
+        # Check if any story ID appears
+        for sid in story_ids:
+            if sid in all_guide_text:
+                found = True
+                break
+        if not found:
+            gaps.append(
+                f"Feature '{feature_name}' has Done stories but no guide "
+                "documentation found in guide/en/"
+            )
+
+    return {
+        "status": "pass" if not gaps else "fail",
+        "gaps": gaps,
+    }

package/lib/changelog_generate.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python3
-"""US-CL-006: changelog generate — deterministic draft generator.
+"""US-CL-006+007: changelog generate — deterministic draft generator.
 
 Extracts ✅ Done stories from .roll/backlog.md, filters internal entries,
 applies mechanical lint, and produces a draft ## Unreleased section.
+Also detects merged PRs since the last release tag that lack a corresponding
+Done story or CHANGELOG entry (gap detection).
 
 Usage:
   python3 lib/changelog_generate.py           # output draft to stdout
@@ -13,6 +15,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+import subprocess
 import sys
 from pathlib import Path
 
@@ -44,9 +47,9 @@ 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.
 
@@ -82,9 +85,8 @@ def _is_internal(desc: str) -> bool:
 
 
 def _clean_description(desc: str) -> str:
-    # Remove depends-on / manual-only tags
+    # Remove depends-on 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
@@ -135,24 +137,33 @@ def _lint_bullet(bullet: str) -> list[str]:
     return viols
 
 
-def _format_bullet(desc: str, source: str) -> str:
-    tag = f" [{source}]" if source else ""
-    return f"- {desc}{tag}"
+def _format_bullet(desc: str, source: str, story_id: str = "") -> str:
+    """Render one clean changelog bullet (deterministic & idempotent, FIX-178):
+
+        - <description>（<ID>） `[source]`
+
+    The story id is appended at the END (never spliced into the sentence) so it
+    is always traceable / audit-matchable without ever mangling the prose. The
+    bold-headline polish in the project's voice is applied by a separate AI pass
+    (configured agent) on top of this raw bullet — deterministic prose splitting
+    on punctuation mangles parentheses/arrows, so it is intentionally avoided.
+    """
+    tag = f" `[{source}]`" if source else ""
+    idref = f"（{story_id}）" if story_id and story_id not in desc else ""
+    return f"- {desc}{idref}{tag}"
 
 
 def _build_draft(groups: dict[str, list[tuple[str, str, str]]]) -> str:
+    # FIX-178: emit clean styled bullets only — lint markers are a separate
+    # concern (stderr summary in main), never inlined into the deliverable.
     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)
+        for story_id, desc, source in groups[cat]:
+            lines.append(_format_bullet(desc, source, story_id))
         lines.append("")
     return "\n".join(lines).rstrip() + "\n"
 
@@ -190,8 +201,158 @@ def _write_to_changelog(draft: str, changelog_path: Path) -> None:
     changelog_path.write_text(text, encoding="utf-8")
 
 
+# ─── US-CL-007: merged PR gap detection ──────────────────────────────────────
+
+
+def _latest_release_tag() -> str | None:
+    """Find the latest v* tag using git."""
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--abbrev=0", "--match", "v*"],
+            capture_output=True, text=True, check=True
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def _commit_log_since_last_release() -> str | None:
+    """Concatenated commit subjects since the last release tag (FIX-177).
+
+    Used for release-aware unreleased detection: a ✅ Done story is unreleased
+    iff its id appears here. Returns None when there is no release tag or git is
+    unavailable, so the caller falls back to the CHANGELOG-text dedup.
+    """
+    tag = _latest_release_tag()
+    if not tag:
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "log", f"{tag}..HEAD", "--pretty=format:%s"],
+            capture_output=True, text=True, check=True
+        )
+        return result.stdout
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def _gh_available() -> bool:
+    """Check whether the gh CLI is installed and on PATH."""
+    try:
+        result = subprocess.run(
+            ["gh", "--version"],
+            capture_output=True, text=True, timeout=5
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _merged_prs_since_tag(tag: str) -> list[tuple[str, str, str]]:
+    """Return list of (pr_number, title, commit_msg) for PRs merged since tag.
+
+    PR numbers are extracted from commit messages (e.g. ``(#123)``).
+    Titles are enriched via ``gh pr view`` when available.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", f"{tag}..HEAD", "--pretty=format:%H %s"],
+            capture_output=True, text=True, check=True
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return []
+
+    prs: list[tuple[str, str, str]] = []
+    seen: set[str] = set()
+    for line in result.stdout.strip().splitlines():
+        if not line:
+            continue
+        parts = line.split(" ", 1)
+        if len(parts) < 2:
+            continue
+        _commit_hash, subject = parts
+        m = re.search(r"\(#(\d+)\)", subject)
+        if not m:
+            continue
+        pr_num = m.group(1)
+        if pr_num in seen:
+            continue
+        seen.add(pr_num)
+
+        title = subject
+        if _gh_available():
+            try:
+                gh_result = subprocess.run(
+                    ["gh", "pr", "view", pr_num, "--json", "title"],
+                    capture_output=True, text=True, timeout=10
+                )
+                if gh_result.returncode == 0:
+                    gh_data = json.loads(gh_result.stdout)
+                    title = gh_data.get("title", subject)
+            except (json.JSONDecodeError, subprocess.TimeoutExpired):
+                pass
+
+        prs.append((pr_num, title, subject))
+    return prs
+
+
+def _pr_in_done_rows(pr_number: str, backlog_path: Path) -> bool:
+    """Check whether the PR number appears in any ✅ Done row of the backlog."""
+    text = backlog_path.read_text(encoding="utf-8")
+    for line in text.splitlines():
+        if "✅ Done" in line and f"#{pr_number}" in line:
+            return True
+    return False
+
+
+def _pr_is_covered(
+    pr_number: str,
+    pr_title: str,
+    commit_msg: str,
+    done_story_ids: set[str],
+    changelog_text: str,
+) -> bool:
+    """Check if a merged PR is already represented in backlog or changelog."""
+    # By PR number in CHANGELOG
+    if f"#{pr_number}" in changelog_text:
+        return True
+    # By story ID appearing in PR title / commit message
+    for story_id in done_story_ids:
+        if story_id and (story_id in pr_title or story_id in commit_msg):
+            return True
+    return False
+
+
+def _uncarded_to_entries(uncarded: list[tuple[str, str]]) -> list[tuple[str, str, str, str]]:
+    """FIX-179: convert uncarded merged PRs (pr_num, title) into draft entries
+    (id, desc, source, category) so they fold into the categorized draft as
+    normal bullets. The old behaviour emitted a separate '⚠️ 待确认 … 请确认'
+    block — a maintainer prompt that must NEVER reach the published CHANGELOG
+    (it leaked into v2.603.1). The "lacked a card" notice now goes to stderr.
+
+    Uses the PR title as the description (stripped of conventional-commit
+    prefixes and the leading id); the story/fix id when present, else PR#<n>.
+    """
+    entries: list[tuple[str, str, str, str]] = []
+    for pr_num, title in uncarded:
+        t = re.sub(
+            r"^\s*(Fix|tcr|docs|chore|feat|refactor|perf|test|Story\s+\d+)\s*[:：]\s*",
+            "", title, flags=re.I,
+        )
+        idm = re.search(r"\b(US-[A-Z]+-\d+|FIX-\d+|REFACTOR-\d+)\b", title)
+        sid = idm.group(1) if idm else f"PR#{pr_num}"
+        if idm:
+            t = re.sub(r"\b" + re.escape(idm.group(1)) + r"\b\s*[:：]?\s*", "", t).strip()
+        cleaned = _clean_description(t) or t.strip()
+        cat = _detect_category(cleaned)
+        src = "loop" if re.search(r"US-AUTO|US-LOOP|FIX-|REFACTOR-", sid) else ""
+        entries.append((sid, cleaned, src, cat))
+    return entries
+
+
 # ─── Main ────────────────────────────────────────────────────────────────────
 
+
 def main() -> int:
     ap = argparse.ArgumentParser(
         description="Generate a draft ## Unreleased section from backlog ✅ Done stories."
@@ -211,9 +372,23 @@ def main() -> int:
 
     rows = _read_done_stories(backlog)
 
+    # FIX-177: only draft stories that are actually UNRELEASED. The backlog holds
+    # every ✅ Done story ever (500+), most already shipped in past versions; the
+    # CHANGELOG only carries recent versions, so filtering by "already in
+    # CHANGELOG text" let hundreds of long-released stories leak into the draft.
+    # Release-aware rule: a story is unreleased iff its id is referenced by a
+    # commit merged since the last release tag (git log <tag>..HEAD). Old stories
+    # never appear there and are correctly excluded. Falls back to the
+    # CHANGELOG-text filter when git/tag are unavailable (e.g. test sandboxes).
+    since_tag_log = _commit_log_since_last_release()
+
     filtered: list[tuple[str, str, str, str]] = []
     for story_id, desc, source in rows:
-        if _already_in_changelog(story_id, desc, changelog):
+        if since_tag_log is not None:
+            # Release-aware: skip stories not named in any post-release commit.
+            if not story_id or story_id not in since_tag_log:
+                continue
+        elif _already_in_changelog(story_id, desc, changelog):
             continue
         if _is_internal(desc):
             continue
@@ -223,31 +398,63 @@ def main() -> int:
         cat = _detect_category(cleaned)
         filtered.append((story_id, cleaned, source, cat))
 
+    # ── US-CL-007: gap detection ───────────────────────────────────────────
+    uncarded: list[tuple[str, str]] = []
+    tag = _latest_release_tag()
+    if tag and _gh_available():
+        merged_prs = _merged_prs_since_tag(tag)
+        done_story_ids = {sid for sid, _desc, _src in rows}
+        changelog_text = changelog.read_text(encoding="utf-8") if changelog.exists() else ""
+        for pr_num, pr_title, commit_msg in merged_prs:
+            if _pr_in_done_rows(pr_num, backlog):
+                continue
+            if _pr_is_covered(pr_num, pr_title, commit_msg, done_story_ids, changelog_text):
+                continue
+            uncarded.append((pr_num, pr_title))
+
     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,
-        )
+        payload = {
+            "stories_found": len(rows),
+            "stories_drafted": len(filtered),
+            "draft": [
+                {"id": sid, "desc": d, "category": c, "source": s}
+                for sid, d, s, c in filtered
+            ],
+            "uncarded_merged": [
+                {"pr": num, "title": title}
+                for num, title in uncarded
+            ],
+        }
+        json.dump(payload, sys.stdout, indent=2, ensure_ascii=False)
         print()
         return 0
 
-    if not filtered:
+    if not filtered and not uncarded:
         print("# No new ✅ Done stories found for CHANGELOG.")
         return 0
 
+    # FIX-179: fold uncarded merged PRs INTO the categorized draft (complete
+    # coverage) rather than a separate '请确认' warning block — that maintainer
+    # prompt must never reach the published CHANGELOG. The "lacked a card"
+    # notice goes to STDERR so the human still sees what to back-fill.
+    all_entries: list[tuple[str, str, str, str]] = list(filtered) + _uncarded_to_entries(uncarded)
+    if uncarded:
+        pr_list = " ".join(f"#{p}" for p, _t in uncarded)
+        print(
+            f"note: {len(uncarded)} 个 merged PR 未建卡,已按 PR 标题并入草稿,建议补卡: {pr_list}",
+            file=sys.stderr,
+        )
+
+    # FIX-178: style-lint warnings go to STDERR so the stdout draft stays clean
+    # (no inline `# lint:` markers in the deliverable). The human still sees them.
+    for story_id, desc, source, _cat in all_entries:
+        viols = _lint_bullet(_format_bullet(desc, source, story_id))
+        if viols:
+            print(f"lint: {story_id or '?'}: {', '.join(viols)}", file=sys.stderr)
+
     groups: dict[str, list[tuple[str, str, str]]] = {}
-    for story_id, desc, source, cat in filtered:
+    for story_id, desc, source, cat in all_entries:
         groups.setdefault(cat, []).append((story_id, desc, source))
-
     draft = _build_draft(groups)
 
     if args.write: