@stylusnexus/work-plan 2026.6.9-2 → 2026.6.9-4

package/README.md

@@ -62,11 +62,13 @@ A dozen more subcommands cover slotting new issues into tracks, closing tracks (
 
 **Coverage + auto-triage** — `coverage --repo=<key>` reports how many open issues fall outside the track model (42% on a real production repo). `auto-triage --repo=<key>` then produces an AI prompt to assign those orphans to existing tracks. Run both periodically to keep the backlog visible.
 
+**Cross-track dependencies** — set `depends_on: [<track-slug>]` in a track's frontmatter to declare explicit dependencies between tracks. The VS Code viewer renders these as thick amber `==>` edges in the dependency graph, and the detail panel shows clickable dependency chips that navigate directly to the dependent track. Set via `/work-plan set <track> depends_on=slug1,slug2` or the "Edit Track Fields" right-click menu in VS Code. Complementary to the issue-derived "owns" edges already inferred from blockers.
+
 Beyond issue tracking, **`plan-status`** answers a different question — *which of your accumulated plan/spec docs actually shipped, half-shipped, or died*. It correlates each plan's declared file-manifest (`Create:`/`Modify:`/`Test:` paths) against git and the filesystem rather than trusting checkboxes (which are routinely left unchecked even for shipped work). Read-only by default; optionally stamp the verdict into each doc (`--stamp`), get an AI verdict on prose/ambiguous docs (`--llm`), and act on the results behind confirmation gates (`--archive` dead plans, `--issues` for partial ones). See [Plan & doc liveness](#plan--doc-liveness-plan-status).
 
 ## How it works
 
-The toolkit treats GitHub as the canonical source of issue state and never tries to mirror it. Track markdown files are lightweight references — they list issue numbers and a few pieces of derived metadata (priority, milestone, `next_up`, last session timestamp). The CLI re-derives everything else live from `gh`, `git`, and the markdown body.
+The toolkit treats GitHub as the canonical source of issue state and never tries to mirror it. Track markdown files are lightweight references — they list issue numbers and a few pieces of derived metadata (priority, milestone, `next_up`, `depends_on`, last session timestamp). The CLI re-derives everything else live from `gh`, `git`, and the markdown body.
 
 ```mermaid
 flowchart TB
@@ -279,7 +281,7 @@ To install for **both** Claude Code AND Codex, run the installer twice with diff
 
 ### VS Code extension
 
-The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph, the Untracked bucket, and full read/write (slot/close/edit/new-track/…) with a public-repo confirm modal.
+The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph (with focus toggle and repo-scoped full map), the Untracked bucket, cross-track dependency chips, per-issue move buttons, and full read/write (slot/close/edit/move/new-track/…) with a public-repo confirm modal.
 
 ![Work Plan VS Code extension — sidebar and dependency graph](https://raw.githubusercontent.com/stylusnexus/work-plan-toolkit/main/vscode/media/screenshots/dependency-graph.png)
 
@@ -378,9 +380,9 @@ work-plan-toolkit/
 │   ├── work-plan/
 │   │   ├── SKILL.md
 │   │   ├── work_plan.py                # CLI entry
-│   │   ├── commands/                   # 16 subcommand modules
+│   │   ├── commands/                   # 24 subcommand modules
 │   │   ├── lib/                        # config, frontmatter, gh, git, prompts, …
-│   │   └── tests/                      # 234 unittest cases
+│   │   └── tests/                      # 600+ unittest cases
 │   └── repo-activity-summary/
 │       └── SKILL.md                    # bundled companion skill
 ├── commands/
@@ -497,8 +499,8 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
-| `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. |
-| `auto-triage [--repo=<key>] [--apply]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. |
+| `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
+| `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
 | `coverage [--repo=<key>] [--list] [--limit=N]` | Report how many open issues are not in any track. `--list` prints titles. Read-only. |
 | `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). `--draft` previews ADDs/FLAGs without prompting or writing. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
@@ -543,7 +545,7 @@ cd skills/work-plan
 python3 -m unittest discover tests
 ```
 
-234 tests, no external dependencies (mocks `gh`/`git` calls).
+600+ tests, no external dependencies (mocks `gh`/`git` calls).
 
 ## License
 

package/VERSION

@@ -1 +1 @@
-2026.06.09+530f7e8
+2026.06.09+f25e6e1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.9-2",
+  "version": "2026.6.9-4",
   "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"

package/skills/work-plan/commands/auto_triage.py

@@ -61,6 +61,15 @@ def run(args: list[str]) -> int:
     apply_mode = "--apply" in args
     repo_arg = next((a for a in args if a.startswith("--repo=")), None)
 
+    limit = 100
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
     try:
         cfg = load_config()
     except ConfigError as e:
@@ -139,13 +148,17 @@ def run(args: list[str]) -> int:
 
     print()
     print("Untracked issues to assign:")
-    for i in untracked:
+    shown = untracked[:limit]
+    for i in shown:
         num = i.get("number", "?")
         title = i.get("title", "")
         milestone = i.get("milestone") or {}
         m_title = milestone.get("title", "—") if isinstance(milestone, dict) else "—"
         labels = [lb["name"] for lb in (i.get("labels") or [])]
         print(f"  #{num} [{m_title}] [{','.join(labels) or 'no-labels'}] {title}")
+    remainder = len(untracked) - len(shown)
+    if remainder > 0:
+        print(f"  … and {remainder} more issues (use --limit=N to show more)")
 
     print("=" * 60)
     print()

package/skills/work-plan/commands/canonicalize.py

@@ -77,6 +77,7 @@ def run(args: list[str]) -> int:
 
         new_body = _insert_canonical_table(
             track.body, issue_nums, issues_by_num, replace=force,
+            milestone_alignment=track.meta.get("milestone_alignment"),
         )
         write_file(track.path, track.meta, new_body)
         print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
@@ -88,9 +89,10 @@ def run(args: list[str]) -> int:
 
 
 def _insert_canonical_table(body: str, issue_nums: list[int],
-                            issues_by_num: dict, replace: bool = False) -> str:
+                            issues_by_num: dict, replace: bool = False,
+                            milestone_alignment=None) -> str:
     """Insert (or replace) a canonical table at the top of the body."""
-    table_md = _render_canonical_table(issue_nums, issues_by_num)
+    table_md = _render_canonical_table(issue_nums, issues_by_num, milestone_alignment)
 
     if replace:
         # Strip existing canonical block (marker + heading + table + separator)
@@ -102,22 +104,57 @@ def _insert_canonical_table(body: str, issue_nums: list[int],
     return leading_whitespace + table_md + "\n---\n\n" + body_stripped
 
 
-def _render_canonical_table(issue_nums: list[int], issues_by_num: dict) -> str:
+def _render_canonical_table(issue_nums: list[int], issues_by_num: dict,
+                            milestone_alignment=None) -> str:
     lines = [
         "## Issues (canonical)",
         "",
         f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
         "",
-        "| # | Title | Assignee | Status |",
-        "|---|---|---|---|",
     ]
+
+    # Build a normalized issue list with compact milestone strings.
+    from lib.github_state import short_milestone
+    norm_issues = []
     for num in sorted(issue_nums):
-        i = issues_by_num.get(num, {})
-        lines.append(render_issue_row(
-            num, i.get("title", "(not fetched)"),
-            format_assignees(i), state_to_status_label(i.get("state")),
-        ))
-    lines.append("")
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm_issues.append({"number": num, "milestone": ms, "_gh": gh})
+
+    from lib.export_model import group_issues_by_milestone
+    groups = group_issues_by_milestone(norm_issues, milestone_alignment)
+
+    if len(groups) <= 1:
+        # Single milestone group (or all null) — render flat, same as before.
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        for num in sorted(issue_nums):
+            i = issues_by_num.get(num, {})
+            lines.append(render_issue_row(
+                num, i.get("title", "(not fetched)"),
+                format_assignees(i), state_to_status_label(i.get("state")),
+            ))
+        lines.append("")
+        return "\n".join(lines)
+
+    # Multiple milestone groups — render with section headings.
+    for label, issues in groups:
+        if label:
+            heading = f"{label} ({len(issues)})"
+        else:
+            heading = f"No milestone ({len(issues)})"
+        lines.append(f"### {heading}")
+        lines.append("")
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        for norm in issues:
+            num = norm["number"]
+            i = norm["_gh"]
+            lines.append(render_issue_row(
+                num, i.get("title", "(not fetched)"),
+                format_assignees(i), state_to_status_label(i.get("state")),
+            ))
+        lines.append("")
     return "\n".join(lines)
 
 

package/skills/work-plan/commands/group.py

@@ -63,6 +63,15 @@ def run(args: list[str]) -> int:
     label_arg = next((a for a in args if a.startswith("--label=")), None)
     state_arg = next((a for a in args if a.startswith("--state=")), None)
 
+    limit = 100
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
     try:
         cfg = load_config()
     except ConfigError as e:
@@ -123,11 +132,15 @@ def run(args: list[str]) -> int:
     print()
     print("=" * 60)
     print(PROMPT_TEMPLATE)
-    for i in issues:
+    shown = issues[:limit]
+    for i in shown:
         m = i.get("milestone", {})
         m_title = m.get("title", "—") if m else "—"
         labels = [l["name"] for l in i.get("labels", [])]
         print(f"#{i['number']} [{m_title}] [{','.join(labels) or 'no-labels'}] {i['title']}")
+    remainder = len(issues) - len(shown)
+    if remainder > 0:
+        print(f"… and {remainder} more issues (use --limit=N to show more)")
     print("=" * 60)
     print()
     print(f"After agent returns clusters JSON, save to {_answers_path()}")
@@ -202,7 +215,9 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
         slug = _slugify(cluster["slug"])
         name = cluster.get("name", slug)
         summary = cluster.get("summary", "")
-        cluster_issues = sorted(set(cluster.get("issues") or []))
+        cluster_issues = _sort_by_milestone(
+            sorted(set(cluster.get("issues") or [])), issues_by_num, batch_milestone,
+        )
         if not cluster_issues:
             print(f"  SKIP {slug}: no issues")
             continue
@@ -214,7 +229,10 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
                 print(f"  SKIP {slug}: file exists but has no frontmatter; use init first")
                 continue
             existing_issues = list(existing_meta.get("github", {}).get("issues") or [])
-            merged = sorted(set(existing_issues) | set(cluster_issues))
+            merged = _sort_by_milestone(
+                sorted(set(existing_issues) | set(cluster_issues)), issues_by_num,
+                existing_meta.get("milestone_alignment") or batch_milestone,
+            )
             existing_meta.setdefault("github", {})["issues"] = merged
             existing_meta["last_touched"] = datetime.now().strftime("%Y-%m-%dT%H:%M")
             write_file(path, existing_meta, existing_body)
@@ -228,7 +246,7 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
                 "launch_priority": "P3",
                 "milestone_alignment": batch_milestone,
                 "github": {"repo": repo, "issues": cluster_issues, "branches": []},
-                "related_tracks": [],
+                "depends_on": [],
                 "last_touched": now, "last_handoff": now,
                 "next_up": [], "blockers": [],
             }
@@ -246,6 +264,26 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
     return 0
 
 
+def _sort_by_milestone(issue_nums, issues_by_num, milestone_alignment=None):
+    """Return issue_nums sorted by milestone then number.
+
+    milestone_alignment issues come first, then other non-null milestones
+    (grouped by label), then null-milestone issues last.  Graceful fallback:
+    if no milestone data is available, falls back to pure numeric sort.
+    """
+    from lib.export_model import milestone_sort_key
+    from lib.github_state import short_milestone
+
+    norm = []
+    for num in issue_nums:
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm.append({"number": num, "milestone": ms})
+
+    norm.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
+    return [i["number"] for i in norm]
+
+
 def _slugify(s: str) -> str:
     s = s.strip().lower()
     s = re.sub(r"[^a-z0-9-]+", "-", s)

package/skills/work-plan/commands/init.py

@@ -119,7 +119,7 @@ def run(args: list[str]) -> int:
         "launch_priority": priority,
         "milestone_alignment": milestone,
         "github": {"repo": repo or "TBD", "issues": issue_nums, "branches": []},
-        "related_tracks": [],
+        "depends_on": [],
         "last_touched": now, "last_handoff": now,
         "next_up": [], "blockers": [],
     }

package/skills/work-plan/commands/move.py

@@ -0,0 +1,131 @@
+"""move subcommand — source-first issue relocation between tracks."""
+import json
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    """move <issue-num> <from-track> <to-track> [--confirm=<token>] [--repo=<key>]
+
+    Removes <issue-num> from <from-track>'s frontmatter and adds it to
+    <to-track>'s frontmatter.  Both tracks must be active and in the same
+    repo.  Public-repo writes gate behind --confirm (same flow as slot/set).
+    """
+    flags, positional = parse_flags(args, {"--confirm", "--repo"})
+    if len(positional) < 3:
+        print("usage: work_plan.py move <issue-num> <from-track> <to-track> [--confirm=<token>] [--repo=<key>]")
+        return 2
+
+    try:
+        issue_num = int(positional[0])
+    except ValueError:
+        print(f"ERROR: '{positional[0]}' is not an issue number.")
+        return 2
+
+    from_arg, to_arg = positional[1], positional[2]
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    # Resolve from-track
+    from_name = from_arg
+    repo_qualifier = repo_flag
+    name_from, repo_from = parse_track_repo_arg(from_arg)
+    if name_from:
+        from_name = name_from
+    if repo_from:
+        repo_qualifier = repo_from
+
+    # Resolve to-track (may override repo qualifier)
+    to_name = to_arg
+    name_to, repo_to = parse_track_repo_arg(to_arg)
+    if name_to:
+        to_name = name_to
+    if repo_to:
+        repo_qualifier = repo_to
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    # Find both tracks (active only)
+    try:
+        src = find_track_by_name(from_name, tracks, active_only=True, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+
+    if not src:
+        print(f"No active track matching '{from_name}'.")
+        return 1
+
+    try:
+        dst = find_track_by_name(to_name, tracks, active_only=True, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+
+    if not dst:
+        print(f"No active track matching '{to_name}'.")
+        return 1
+
+    # Same-repo guard
+    if src.repo != dst.repo:
+        print(f"ERROR: cross-repo moves not supported ({src.repo} ≠ {dst.repo}).")
+        return 1
+
+    # Same-track no-op
+    if src.name == dst.name:
+        print(f"#{issue_num} already in track '{src.name}'.")
+        return 0
+
+    # Validate issue is in source
+    src_issues = list(src.meta.get("github", {}).get("issues") or [])
+    if issue_num not in src_issues:
+        print(f"ERROR: #{issue_num} is not in track '{src.name}'.")
+        return 1
+
+    # Check if already in destination
+    dst_issues = list(dst.meta.get("github", {}).get("issues") or [])
+    if issue_num in dst_issues:
+        print(f"#{issue_num} already in track '{dst.name}'. Removing from '{src.name}' only.")
+        # Still remove from source even if already in dest
+        src_issues.remove(issue_num)
+        src.meta.setdefault("github", {})["issues"] = src_issues
+        write_file(src.path, src.meta, src.body)
+        print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+        return 0
+
+    # Public-repo confirm gate (on the destination write)
+    confirm = flags.get("--confirm")
+    if dst.repo and needs_confirm(dst.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, dst.repo, dst.name)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{dst.repo} is PUBLIC (or visibility unknown); "
+                f"moving #{issue_num} will be written there."
+            ),
+            "token": make_token(dst.repo, dst.name),
+        }))
+        return 0
+
+    # Execute: remove from source, add to destination
+    src_issues.remove(issue_num)
+    src.meta.setdefault("github", {})["issues"] = src_issues
+    write_file(src.path, src.meta, src.body)
+    print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+
+    dst_issues.append(issue_num)
+    dst.meta.setdefault("github", {})["issues"] = sorted(dst_issues)
+    write_file(dst.path, dst.meta, dst.body)
+    print(f"  ✓ Added #{issue_num} to '{dst.name}'.")
+
+    return 0

package/skills/work-plan/commands/new_track.py

@@ -193,7 +193,7 @@ def run(args: list[str]) -> int:
         "launch_priority": priority,
         "milestone_alignment": milestone,
         "github": {"repo": github, "issues": [], "branches": []},
-        "related_tracks": [],
+        "depends_on": [],
         "last_touched": now,
         "last_handoff": now,
         "next_up": [],

package/skills/work-plan/commands/set_field.py

@@ -6,7 +6,7 @@ from lib.frontmatter import write_file
 from lib.write_guard import needs_confirm, make_token, valid_token
 from lib.prompts import parse_flags
 
-ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up"}
+ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up", "depends_on"}
 LIST_FIELDS = {"blockers", "next_up"}
 STATUSES = {"active", "in-progress", "blocked", "parked", "shipped", "abandoned"}
 
@@ -29,7 +29,10 @@ def run(args: list[str]) -> int:
         k, v = a.split("=", 1)
         if k not in ALLOWED:
             print(f"ERROR: field {k!r} not settable (allowed: {sorted(ALLOWED)})"); return 2
-        if k in LIST_FIELDS:
+        if k == "depends_on":
+            # Comma-separated track slugs (strings, not issue numbers).
+            parsed[k] = [x.strip() for x in v.split(",") if x.strip()] if v.strip() else []
+        elif k in LIST_FIELDS:
             try:
                 parsed[k] = [int(x) for x in v.split(",") if x.strip()] if v.strip() else []
             except ValueError:

package/skills/work-plan/commands/where_was_i.py

@@ -25,7 +25,7 @@ from pathlib import Path
 from typing import Optional
 
 from lib.config import load_config, ConfigError
-from lib.tracks import discover_tracks, find_track_by_name
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
 from lib.prompts import prompt_input, parse_flags
 from lib.github_state import fetch_issues, short_milestone
 from lib.git_state import (
@@ -40,8 +40,18 @@ RULE_WIDTH = 57
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--pick"})
-    track_name = positional[0] if positional else None
+    flags, positional = parse_flags(args, {"--pick", "--repo"})
+    track_arg = positional[0] if positional else None
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    # Resolve track name and repo qualifier from <track>@<repo> syntax
+    track_name = track_arg
+    repo_qualifier = repo_flag
+    if track_arg:
+        name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+        track_name = name_from_arg
+        if repo_from_arg:
+            repo_qualifier = repo_from_arg
 
     try:
         cfg = load_config()
@@ -78,12 +88,20 @@ def run(args: list[str]) -> int:
                 return 1
             track = active[idx]
         else:
-            track = find_track_by_name(choice, tracks)
+            try:
+                track = find_track_by_name(choice, tracks, repo=repo_qualifier)
+            except AmbiguousTrackError as e:
+                print(str(e))
+                return 1
             if not track:
                 print(f"No track matching '{choice}'.")
                 return 1
     else:
-        track = find_track_by_name(track_name, tracks)
+        try:
+            track = find_track_by_name(track_name, tracks, repo=repo_qualifier)
+        except AmbiguousTrackError as e:
+            print(str(e))
+            return 1
         if not track:
             print(f"No track matching '{track_name}'.")
             return 1

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

@@ -3,6 +3,55 @@ from lib.github_state import format_assignees, short_milestone
 
 SCHEMA = 1
 
+
+def milestone_sort_key(issue: dict, milestone_alignment=None):
+    """Sort key for an issue dict (must have 'number' and 'milestone').
+
+    Returns (tier, milestone_label, number) so that:
+      0. issues matching milestone_alignment come first
+      1. issues with other non-null milestones come next, grouped by label
+      2. issues with null/empty milestone come last.
+
+    milestone may be a compact string (as from short_milestone) or None.
+    """
+    ms = issue.get("milestone")
+    num = issue.get("number", 0) or 0
+    if ms is None or ms == "":
+        return (2, "", num)
+    if ms == milestone_alignment:
+        return (0, ms, num)
+    return (1, ms, num)
+
+
+def group_issues_by_milestone(issues, milestone_alignment=None):
+    """Partition sorted issues into [(label, [issue, ...]), ...].
+
+    label is the compact milestone string; None for the no-milestone group.
+    Groups are emitted in milestone_sort_key order.  A single-group result
+    means all issues share the same milestone (or all lack one) — callers
+    can use this to decide whether to render section headings.
+    """
+    if not issues:
+        return []
+    sorted_issues = sorted(issues,
+                           key=lambda i: milestone_sort_key(i, milestone_alignment))
+    groups = []
+    current_label = None  # sentinel — always differs from the first real label
+    current_group = []
+    for i in sorted_issues:
+        label = i.get("milestone") or None
+        if label != current_label:
+            if current_group:
+                groups.append((current_label, current_group))
+            current_label = label
+            current_group = [i]
+        else:
+            current_group.append(i)
+    if current_group:
+        groups.append((current_label, current_group))
+    return groups
+
+
 def _issue(i: dict) -> dict:
     state = (i.get("state") or "OPEN").lower()
     return {
@@ -13,11 +62,14 @@ def _issue(i: dict) -> dict:
         "milestone": short_milestone(i.get("milestone")) or None,
     }
 
+
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None) -> dict:
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
     for t in tracks:
         issues = [_issue(i) for i in issues_by_track.get(t.name, [])]
+        milestone_alignment = t.meta.get("milestone_alignment")
+        issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")
         closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
         next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
@@ -27,10 +79,11 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "tier": getattr(t, "tier", "private") or "private",
             "status": t.meta.get("status"),
             "launch_priority": t.meta.get("launch_priority"),
-            "milestone_alignment": t.meta.get("milestone_alignment"),
+            "milestone_alignment": milestone_alignment,
             "visibility": visibility.get(t.repo),
             "blockers": list(t.meta.get("blockers") or []),
             "next_up": next_up,
+            "depends_on": list(t.meta.get("depends_on") or []),
             "rollup": {"open": opened, "closed": len(issues) - opened},
             "issues": issues,
         })