@stylusnexus/work-plan 2026.6.9

package/skills/work-plan/lib/github_state.py

@@ -0,0 +1,296 @@
+"""Query GitHub via `gh`."""
+import json
+import re
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from typing import Iterable, Optional
+
+PRIORITY_LABELS = ("priority/P0", "priority/P1", "priority/P2", "priority/P3")
+DEFAULT_PRIORITY = "P3"
+
+MAX_FETCH_WORKERS = 8
+
+_GH_ISSUE_FIELDS = "number,state,labels,title,milestone,url,closedAt,body,updatedAt,assignees"
+
+_REPO_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
+GQL_CHUNK = 100  # issues per GraphQL query; GitHub GraphQL complexity budget ~5000 pts/query, 100 issueOrPullRequest nodes is well within it
+
+
+def fetch_issue(repo: str, number: int) -> Optional[dict]:
+    """Fetch a single issue via gh. Returns parsed dict on success, None on failure.
+    Never raises — a missing `gh` binary or any subprocess error yields None."""
+    try:
+        proc = subprocess.run(
+            ["gh", "issue", "view", str(number),
+             "--repo", repo,
+             "--json", _GH_ISSUE_FIELDS],
+            capture_output=True, text=True,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def fetch_issues(repo: str, issue_numbers: Iterable[int]) -> list[dict]:
+    """Fetch state of multiple issues via gh (sequential). Unchanged semantics."""
+    nums = list(issue_numbers)
+    if not nums:
+        return []
+    results = []
+    for num in nums:
+        result = fetch_issue(repo, num)
+        if result is not None:
+            results.append(result)
+    return results
+
+
+def fetch_issues_concurrent(jobs: Iterable[tuple], max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch multiple (repo, number) pairs concurrently.
+
+    Dedupes jobs (first-seen order preserved). Returns a dict keyed by
+    (repo, number) containing only successful fetches (None results omitted).
+    Empty jobs -> {}.
+    """
+    unique_jobs = list(dict.fromkeys(jobs))
+    if not unique_jobs:
+        return {}
+    workers = min(max_workers, len(unique_jobs))
+    result: dict[tuple, dict] = {}
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(fetch_issue, repo, num): (repo, num)
+                   for repo, num in unique_jobs}
+        for future, key in futures.items():
+            issue = future.result()
+            if issue is not None:
+                result[key] = issue
+    return result
+
+
+def _normalize_gql_node(node) -> Optional[dict]:
+    """Reshape a GraphQL issueOrPullRequest node into the REST-ish shape export_model
+    expects (assignees as [{login}], milestone as {title}|None). None for a null node.
+    On success returns a dict with keys: number, title, state, assignees, milestone."""
+    if not node:
+        return None
+    assignees = [{"login": a.get("login")} for a in
+                 ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
+    ms = node.get("milestone")
+    return {
+        "number": node.get("number"),
+        "title": node.get("title", ""),
+        "state": node.get("state", "OPEN"),
+        "assignees": assignees,
+        "milestone": {"title": ms["title"]} if ms and ms.get("title") else None,
+    }
+
+
+def _gql_query(owner: str, name: str, numbers: list) -> str:
+    fields = ("number title state assignees(first: 10) { nodes { login } } milestone { title }")
+    aliases = "\n".join(
+        f'  i{n}: issueOrPullRequest(number: {int(n)}) {{ '
+        f'... on Issue {{ {fields} }} ... on PullRequest {{ {fields} }} }}'
+        for n in numbers
+    )
+    return f'query {{ repository(owner: "{owner}", name: "{name}") {{\n{aliases}\n}} }}'
+
+
+def fetch_repo_issues_graphql(repo: str, numbers, chunk: int = GQL_CHUNK,
+                              max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch exactly `numbers` from `repo` via batched GraphQL (issueOrPullRequest, so
+    PRs are included). Returns {number: normalized_issue} for those found. Never raises;
+    missing/null/errored numbers are simply omitted (caller may fall back per-issue)."""
+    try:
+        nums = list(dict.fromkeys(int(n) for n in numbers))
+    except (ValueError, TypeError):
+        return {}
+    if not nums or not _REPO_RE.match(repo or ""):
+        return {}
+    owner, name = repo.split("/", 1)
+    chunks = [nums[i:i + chunk] for i in range(0, len(nums), chunk)]
+
+    def _run(batch):
+        try:
+            proc = subprocess.run(
+                ["gh", "api", "graphql", "-f", "query=" + _gql_query(owner, name, batch)],
+                capture_output=True, text=True,
+            )
+        except Exception:
+            return {}
+        if proc.returncode != 0 or not proc.stdout.strip():
+            return {}
+        try:
+            data = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            return {}
+        repo_obj = ((data.get("data") or {}).get("repository") or {})
+        out = {}
+        for node in repo_obj.values():
+            norm = _normalize_gql_node(node)
+            if norm and norm.get("number") is not None:
+                out[norm["number"]] = norm
+        return out
+
+    result = {}
+    with ThreadPoolExecutor(max_workers=min(max_workers, len(chunks))) as ex:
+        for part in ex.map(_run, chunks):
+            result.update(part)
+    return result
+
+
+def fetch_export_issues(repo_to_numbers: dict, max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch referenced issues for the viewer export with minimal gh calls: batched
+    GraphQL per repo (only the referenced numbers; includes PRs), run concurrently
+    across repos, with a per-issue fallback for anything GraphQL didn't return.
+    Returns {(repo, number): issue_dict}. Never raises."""
+    repos = [r for r, nums in repo_to_numbers.items() if r and nums]
+    if not repos:
+        return {}
+    try:
+        with ThreadPoolExecutor(max_workers=min(max_workers, len(repos))) as ex:
+            gql_by_repo = dict(zip(repos, ex.map(
+                lambda r: fetch_repo_issues_graphql(r, repo_to_numbers[r], max_workers=max_workers),
+                repos)))
+    except Exception:
+        gql_by_repo = {r: {} for r in repos}
+    result, missing = {}, []
+    for repo, numbers in repo_to_numbers.items():
+        if not repo or not numbers:
+            continue
+        got = gql_by_repo.get(repo, {})
+        for n in numbers:
+            if n in got:
+                result[(repo, n)] = got[n]
+            else:
+                missing.append((repo, n))
+    if missing:
+        result.update(fetch_issues_concurrent(missing, max_workers=max_workers))
+    return result
+
+
+def fetch_open_issues(repo: str, limit: int = 1000) -> list[dict]:
+    """All OPEN issues for `repo` as gh rows ({number,title,assignees,milestone,state}).
+    One `gh issue list` call. Never raises — returns [] on any error/bad repo."""
+    if not _REPO_RE.match(repo or ""):
+        return []
+    try:
+        proc = subprocess.run(
+            ["gh", "issue", "list", "--repo", repo,
+             "--state", "open",
+             "--json", "number,title,state,assignees,milestone",
+             "--limit", str(limit)],
+            capture_output=True, text=True,
+        )
+    except Exception:
+        return []
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return []
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return []
+
+
+def fetch_recent_issues(repo: str, since_iso: str, extra_labels: list[str] = None) -> list[dict]:
+    """Fetch issues created since `since_iso` (date YYYY-MM-DD)."""
+    search = f"created:>={since_iso}"
+    cmd = ["gh", "issue", "list", "--repo", repo,
+           "--state", "all",
+           "--search", search,
+           "--limit", "50",
+           "--json", "number,title,labels,createdAt,milestone,url"]
+    if extra_labels:
+        for lab in extra_labels:
+            cmd.extend(["--label", lab])
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        return []
+    return json.loads(proc.stdout) if proc.stdout.strip() else []
+
+
+_VIS_CACHE: dict = {}
+
+
+def repo_visibility(repo: str) -> Optional[str]:
+    """Best-effort repo visibility ('PUBLIC'/'PRIVATE') via gh; None if unknown.
+    Memoized per process. Never raises — unknown visibility is a valid answer."""
+    if not repo:
+        return None
+    if repo in _VIS_CACHE:
+        return _VIS_CACHE[repo]
+    proc = subprocess.run(
+        ["gh", "repo", "view", repo, "--json", "visibility"],
+        capture_output=True, text=True,
+    )
+    vis = None
+    if proc.returncode == 0 and proc.stdout.strip():
+        try:
+            vis = json.loads(proc.stdout).get("visibility")
+        except json.JSONDecodeError:
+            vis = None
+    _VIS_CACHE[repo] = vis
+    return vis
+
+
+def extract_priority(labels: list[dict]) -> str:
+    label_names = {l["name"] for l in labels}
+    for p in PRIORITY_LABELS:
+        if p in label_names:
+            return p.split("/")[1]
+    return DEFAULT_PRIORITY
+
+
+def short_milestone(milestone) -> str:
+    """Extract a compact milestone tag from a gh milestone object.
+
+    gh returns milestone as `{"title": "v0.4.0 — MVP Go-Live Gate", ...}` or null.
+    The leading token (e.g. `v0.4.0`) is what tracks declare in
+    `milestone_alignment:`, so it's the natural form to show in tight per-issue
+    lines. Returns "" when milestone is missing or has no title.
+    """
+    if not milestone:
+        return ""
+    title = milestone.get("title") if isinstance(milestone, dict) else None
+    if not title:
+        return ""
+    return title.split()[0] if title.split() else ""
+
+
+def format_assignees(issue: dict) -> str:
+    """Render a canonical-table assignee cell from an issue's assignees.
+
+    Returns `@login, @login` for one or more assignees, or `—` when there are
+    none (or the issue dict is missing). Matches the placeholder used by
+    canonicalize so appended rows are visually consistent.
+    """
+    assignees = (issue or {}).get("assignees") or []
+    logins = [f"@{a['login']}" for a in assignees if a.get("login")]
+    return ", ".join(logins) if logins else "—"
+
+
+def state_to_status_label(state: str) -> str:
+    """Map a GitHub issue/PR state to a human-readable status label.
+
+    CLOSED and MERGED both map to ✅ Shipped (gh treats PRs as a kind of
+    issue, so issue-API responses can return MERGED for PR refs).
+    """
+    s = (state or "OPEN").upper()
+    if s in ("CLOSED", "MERGED"):
+        return "✅ Shipped"
+    return "🔲 Open"
+
+
+def create_issue(repo: str, title: str, body: str) -> Optional[str]:
+    """Open a GitHub issue via `gh issue create`. Returns the issue URL, or None
+    on failure. Reuses the user's `gh` auth; never touches tokens."""
+    proc = subprocess.run(
+        ["gh", "issue", "create", "--repo", repo, "--title", title, "--body", body],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None

package/skills/work-plan/lib/llm_evidence.py

@@ -0,0 +1,45 @@
+"""Pick the docs that need an LLM verdict and gather evidence for the judgment.
+
+Two kinds of candidate mechanical scoring can't resolve:
+  - manifest-less: prose docs (design specs) with no Create/Modify/Test paths.
+  - ambiguous: a manifest exists but <AMBIGUOUS_PCT of files are satisfied — the
+    suspicious "0/N looks unstarted but was recently touched" cases, usually
+    Modify-heavy plans the file-existence signal under-counts.
+"""
+from lib import git_state
+
+AMBIGUOUS_PCT = 20.0
+EXCERPT_CHARS = 1500
+
+
+def select_candidates(rows: list) -> list:
+    """From evaluated rows, return those needing an LLM verdict."""
+    out = []
+    for r in rows:
+        if r["verdict"] == "manifest-less":
+            out.append(r)
+        elif r["files_declared"] > 0:
+            pct = r["files_present"] / r["files_declared"] * 100.0
+            if pct < AMBIGUOUS_PCT:
+                out.append(r)
+    return out
+
+
+def _first_title(text: str) -> str:
+    for line in text.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return "(no title)"
+
+
+def gather_evidence(doc, repo_root) -> dict:
+    """Build the evidence dict the model uses to judge one doc."""
+    text = doc.path.read_text(encoding="utf-8", errors="replace")
+    last = git_state.path_last_commit_date(doc.rel, repo_root)
+    return {
+        "rel": doc.rel,
+        "kind": doc.kind,
+        "title": _first_title(text),
+        "last_touched": last.date().isoformat() if last else None,
+        "excerpt": text[:EXCERPT_CHARS],
+    }

package/skills/work-plan/lib/manifest.py

@@ -0,0 +1,164 @@
+"""Parse a plan's declared file-manifest + checkboxes, and score it against
+the filesystem and git. The honest completion signal is which declared files
+actually exist / were committed — not the (unreliable) checkbox state.
+"""
+import re
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Callable, Optional
+
+# Matches:  Create: `path`  /  Modify: `path:120-145`  /  Test: `path`
+PATH_RE = re.compile(r"\b(Create|Modify|Test):\s*`([^`]+)`")
+# Trailing line spec: ':120', ':120-145', or comma-joined ':104-115,217-247'
+_RANGE_RE = re.compile(r":\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$")
+_CHK_DONE = re.compile(r"^\s*- \[x\]", re.I | re.M)
+_CHK_TODO = re.compile(r"^\s*- \[ \]", re.M)
+_DATE_RE = re.compile(r"(\d{4})-(\d{2})-(\d{2})")
+
+
+@dataclass(frozen=True)
+class DeclaredPath:
+    kind: str   # "create" | "modify" | "test"
+    path: str   # repo-relative, line-range stripped
+
+
+def strip_range(p: str) -> str:
+    """'src/foo.ts:120-145' -> 'src/foo.ts'; bare paths unchanged."""
+    return _RANGE_RE.sub("", p.strip())
+
+
+def parse_declared_paths(text: str) -> list:
+    """Extract declared file paths. First kind seen per path wins (dedup)."""
+    seen = {}  # path -> kind
+    for kind, raw in PATH_RE.findall(text):
+        p = strip_range(raw)
+        if "/" not in p:                       # skip bare tokens / commands
+            continue
+        if p.startswith(("http", "git ")):     # skip urls / shell
+            continue
+        seen.setdefault(p, kind.lower())
+    return [DeclaredPath(kind=k, path=p) for p, k in seen.items()]
+
+
+def count_checkboxes(text: str) -> tuple:
+    """Return (done, total) markdown task checkboxes."""
+    done = len(_CHK_DONE.findall(text))
+    todo = len(_CHK_TODO.findall(text))
+    return done, done + todo
+
+
+def plan_date_from_filename(filename: str) -> Optional[date]:
+    """Pull a YYYY-MM-DD prefix out of a plan filename, if present."""
+    m = _DATE_RE.search(filename)
+    if not m:
+        return None
+    try:
+        return date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+    except ValueError:
+        return None
+
+
+def is_in_tree(path: str, repo_root) -> bool:
+    """True if a declared path resolves inside repo_root. A '~'-rooted path, an
+    absolute path elsewhere, or a '..'-escaping path is out-of-tree."""
+    if path.startswith("~"):
+        return False
+    root = Path(repo_root).resolve()
+    p = Path(path)
+    target = p.resolve() if p.is_absolute() else (root / p).resolve()
+    try:
+        target.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def out_of_tree_ratio(decls: list, repo_root) -> float:
+    """Fraction of declared paths resolving outside repo_root (0.0 if none declared)."""
+    if not decls:
+        return 0.0
+    out = sum(1 for d in decls if not is_in_tree(d.path, repo_root))
+    return out / len(decls)
+
+
+@dataclass
+class ManifestScore:
+    total: int
+    satisfied: int
+    by_kind: dict   # {"create": (sat, tot), "modify": (sat, tot), "test": (sat, tot)}
+
+    @property
+    def pct(self) -> Optional[float]:
+        return (self.satisfied / self.total * 100.0) if self.total else None
+
+
+def _path_satisfied(d, exists, committed_since) -> bool:
+    return committed_since(d.path) if d.kind == "modify" else exists(d.path)
+
+
+def score_manifest(
+    decls: list,
+    repo_root: Path,
+    plan_date: Optional[date],
+    *,
+    exists: Optional[Callable] = None,
+    committed_since: Optional[Callable] = None,
+) -> ManifestScore:
+    """Score declared paths. `Create`/`Test` count if the file exists now;
+    `Modify` counts only if the file was committed on/after `plan_date`
+    (existence alone is meaningless for a pre-existing modify target).
+
+    `exists(rel)->bool` and `committed_since(rel)->bool` are injectable for
+    offline testing; defaults wire to the filesystem and git.
+    """
+    if exists is None:
+        exists = lambda rel: (Path(repo_root) / rel).exists()
+    if committed_since is None:
+        from lib import git_state
+        # Deliberate degradation: with no plan date we can't ask "committed since
+        # when?", so a Modify falls back to mere existence. This can over-count an
+        # undated plan's Modify targets — accepted because superpowers plans carry a
+        # YYYY-MM-DD filename prefix, so the dateless path is rare in practice.
+        committed_since = (
+            (lambda rel: git_state.path_committed_since(rel, plan_date, repo_root))
+            if plan_date is not None
+            else (lambda rel: (Path(repo_root) / rel).exists())
+        )
+
+    by = {"create": [0, 0], "modify": [0, 0], "test": [0, 0]}
+    satisfied = 0
+    for d in decls:
+        by[d.kind][1] += 1
+        if _path_satisfied(d, exists, committed_since):
+            by[d.kind][0] += 1
+            satisfied += 1
+    return ManifestScore(
+        total=len(decls),
+        satisfied=satisfied,
+        by_kind={k: tuple(v) for k, v in by.items()},
+    )
+
+
+def unsatisfied_paths(
+    decls: list,
+    repo_root: Path,
+    plan_date: Optional[date],
+    *,
+    exists: Optional[Callable] = None,
+    committed_since: Optional[Callable] = None,
+) -> list:
+    """Return the declared paths that are NOT satisfied (missing / not committed).
+
+    Same satisfaction rule and injectable predicates as `score_manifest`.
+    """
+    if exists is None:
+        exists = lambda rel: (Path(repo_root) / rel).exists()
+    if committed_since is None:
+        from lib import git_state
+        committed_since = (
+            (lambda rel: git_state.path_committed_since(rel, plan_date, repo_root))
+            if plan_date is not None
+            else (lambda rel: (Path(repo_root) / rel).exists())
+        )
+    return [d for d in decls if not _path_satisfied(d, exists, committed_since)]

package/skills/work-plan/lib/new_issues.py

@@ -0,0 +1,69 @@
+"""Detect new GitHub issues that should slot into existing tracks."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+from lib.github_state import fetch_recent_issues
+
+
+def build_slug_labels(tracks) -> dict[str, list[str]]:
+    """Build a {slug: [labels]} map from tracks with `github.labels` frontmatter.
+
+    Slugs without an explicit `github.labels` are omitted — callers fall back
+    to the default `track/<slug>` pattern in that case.
+    """
+    out: dict[str, list[str]] = {}
+    for t in tracks:
+        if not getattr(t, "has_frontmatter", False):
+            continue
+        slug = t.meta.get("track", t.name)
+        labels = t.meta.get("github", {}).get("labels")
+        if labels:
+            out[slug] = [str(lab) for lab in labels if str(lab).strip()]
+    return out
+
+
+def match_issue_to_tracks(issue: dict, track_slugs: list[str],
+                          *, slug_labels: dict[str, list[str]] | None = None) -> list[str]:
+    """Return slugs of tracks this issue might belong to.
+
+    1. Configured label match → exact match. Each slug uses its own labels from
+       `slug_labels` if provided, else falls back to `[track/<slug>]`.
+    2. Slug words appear in title → fuzzy match (all >=3-char words must appear).
+    """
+    label_names = {l["name"] for l in issue.get("labels", [])}
+    title_lower = issue.get("title", "").lower()
+    overrides = slug_labels or {}
+
+    matches = set()
+    for slug in track_slugs:
+        labels_for_slug = overrides.get(slug) or [f"track/{slug}"]
+        if any(lab in label_names for lab in labels_for_slug):
+            matches.add(slug)
+
+    for slug in track_slugs:
+        if slug in matches:
+            continue
+        words = [w for w in re.split(r"[-_]", slug) if len(w) >= 3]
+        if not words:
+            continue
+        if all(w.lower() in title_lower for w in words):
+            matches.add(slug)
+
+    return sorted(matches)
+
+
+def find_new_issues_for_tracks(repo: str, track_slugs: list[str],
+                               *, slug_labels: dict[str, list[str]] | None = None,
+                               since_days: int = 7) -> dict[str, list[dict]]:
+    """For each track slug, return list of recent issues that match."""
+    if not track_slugs:
+        return {}
+    since_date = (datetime.now() - timedelta(days=since_days)).strftime("%Y-%m-%d")
+    recent = fetch_recent_issues(repo, since_iso=since_date)
+    out: dict[str, list[dict]] = {s: [] for s in track_slugs}
+    for issue in recent:
+        for slug in match_issue_to_tracks(issue, track_slugs, slug_labels=slug_labels):
+            out[slug].append(issue)
+    return out

package/skills/work-plan/lib/next_up.py

@@ -0,0 +1,98 @@
+"""Compute a suggested `next_up` issue list for a track.
+
+Sort policy: open issues only, exclude blockers, ranked by priority label
+(P0 < P1 < P2 < P3 with missing label defaulting to P3), then by most-
+recently-updated within the same priority bucket. Closed issues are
+filtered out — `next_up` should never propose work that's already done.
+
+Used by:
+- `commands/handoff.py` — `--auto-next` flag prompts the user to apply
+  the suggestion (with edit/skip options).
+- `commands/brief.py` — when a track sets `next_up_auto: true` in its
+  frontmatter, brief computes the suggestion live at display time and
+  ignores any stored `next_up` list.
+
+The two callers share this helper so the algorithm has one home; if we
+ever want to layer additional signals (assignee, linked PR, milestone),
+they go here.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Iterable
+
+from lib.github_state import extract_priority, short_milestone
+
+PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+DEFAULT_TOP_N = 3
+
+# Milestone alignment ranks: items on the track's declared milestone come
+# first, items on a different milestone next, items with no milestone last.
+MILESTONE_ALIGNED = 0
+MILESTONE_OTHER = 1
+MILESTONE_NONE = 2
+
+
+def _updated_unix(issue: dict) -> float:
+    """Parse the gh-formatted updatedAt field to a unix timestamp.
+
+    Returns 0.0 if the field is missing or unparsable — treats unknown-age
+    issues as oldest, which keeps recently-updated items on top of the
+    suggestion within the same priority bucket.
+    """
+    raw = issue.get("updatedAt") or ""
+    if not raw:
+        return 0.0
+    try:
+        # gh emits 'Z'-suffixed UTC; fromisoformat in 3.9 wants '+00:00'.
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def suggest_next_up(
+    issues: list[dict],
+    blocker_nums: Iterable[int] | None = None,
+    n: int = DEFAULT_TOP_N,
+    track_milestone: str | None = None,
+) -> list[int]:
+    """Return up to `n` issue numbers ranked for "what to work on next."
+
+    Args:
+        issues: issue dicts as returned by `gh issue list --json
+            number,state,labels,milestone,updatedAt,...`.
+        blocker_nums: iterable of issue numbers to exclude (a track's
+            manually-flagged blockers).
+        n: maximum items to return. Default is DEFAULT_TOP_N.
+        track_milestone: optional `milestone_alignment:` value from the
+            track's frontmatter (e.g. `"v0.4.0"`). When provided, issues
+            on this milestone rank above items on any other milestone,
+            which in turn rank above items with no milestone — keeps
+            post-launch deferrals from polluting a launch-window list.
+
+    Returns:
+        List of issue numbers, highest-ranked first. Empty if nothing
+        qualifies (e.g., everything closed or blocked).
+    """
+    blockers = set(blocker_nums or [])
+    candidates = [
+        i for i in issues
+        if str(i.get("state", "")).upper() == "OPEN"
+        and i.get("number") not in blockers
+    ]
+
+    def milestone_rank(issue: dict) -> int:
+        ms = short_milestone(issue.get("milestone"))
+        if not ms:
+            return MILESTONE_NONE
+        if track_milestone and ms == track_milestone:
+            return MILESTONE_ALIGNED
+        return MILESTONE_OTHER
+
+    def sort_key(issue: dict) -> tuple[int, int, float]:
+        pri = extract_priority(issue.get("labels", []))
+        # Negate timestamp so newer comes first within a priority bucket.
+        return (milestone_rank(issue), PRIORITY_RANK.get(pri, 3), -_updated_unix(issue))
+
+    candidates.sort(key=sort_key)
+    return [i["number"] for i in candidates[:n]]