@stylusnexus/work-plan 2026.6.9 → 2026.6.10-2

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

@@ -14,9 +14,11 @@ import sys
 from datetime import datetime
 from pathlib import Path
 
-from lib.config import load_config, ConfigError
+from lib.config import load_config, ConfigError, is_valid_git_repo
 from lib.frontmatter import parse_file, write_file
+from lib.notes_readme import seed_readme
 from lib.scratch import cache_dir
+from lib.write_guard import needs_confirm
 
 
 def _batch_path() -> Path:
@@ -61,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:
@@ -68,7 +79,7 @@ def run(args: list[str]) -> int:
         return 1
 
     if apply_mode:
-        return _apply(cfg)
+        return _apply(cfg, args)
 
     # Resolve repo
     repos = list(cfg["repos"].keys())
@@ -113,6 +124,7 @@ def run(args: list[str]) -> int:
         "repo": repo,
         "folder": folder,
         "milestone": milestone_arg.split("=", 1)[1] if milestone_arg else None,
+        "private": "--private" in args,
         "issues": issues,
     }, indent=2))
 
@@ -120,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()}")
@@ -132,7 +148,9 @@ def run(args: list[str]) -> int:
     return 0
 
 
-def _apply(cfg: dict) -> int:
+def _apply(cfg: dict, args: list[str] = None) -> int:
+    if args is None:
+        args = []
     answers_path = _answers_path()
     batch_path = _batch_path()
     if not answers_path.exists():
@@ -149,13 +167,44 @@ def _apply(cfg: dict) -> int:
         print(f"ERROR: batch folder '{folder}' not in config.yml repos.")
         return 1
     batch_milestone = batch.get("milestone") or "v1.0.0"
+
+    # --private: from current args OR stored in batch (so re-invocation is consistent)
+    use_private = "--private" in args or batch.get("private", False)
+
     answers = json.loads(answers_path.read_text())
 
     notes_root = Path(cfg["notes_root"])
-    track_dir = notes_root / folder
+
+    # Determine track directory: shared (.work-plan/) or private (notes_root/folder/)
+    repo_entry = cfg["repos"].get(folder, {})
+    local_raw = repo_entry.get("local")
+    shared_dir = None
+    if not use_private and local_raw:
+        local_path = Path(local_raw).expanduser()
+        if is_valid_git_repo(local_path):
+            shared_dir = local_path / ".work-plan"
+
+    if shared_dir is not None:
+        track_dir = shared_dir
+        is_shared_route = True
+    else:
+        track_dir = notes_root / folder
+        is_shared_route = False
+
+    # Public-repo heads-up (non-blocking) — print once before processing
+    if is_shared_route and needs_confirm(repo, cfg):
+        print(
+            f"HEADS-UP: {repo} is PUBLIC (or visibility unknown) — shared tracks"
+            " will be committed publicly. Use --private to keep them local."
+        )
+
     if not track_dir.exists():
-        print(f"ERROR: {track_dir} doesn't exist. Create it first.")
-        return 1
+        if is_shared_route:
+            track_dir.mkdir(parents=True, exist_ok=True)
+            seed_readme(track_dir)
+        else:
+            print(f"ERROR: {track_dir} doesn't exist. Create it first.")
+            return 1
 
     issues_by_num = {i["number"]: i for i in batch["issues"]}
 
@@ -166,7 +215,9 @@ def _apply(cfg: dict) -> 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
@@ -178,7 +229,10 @@ def _apply(cfg: dict) -> 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)
@@ -192,13 +246,15 @@ def _apply(cfg: dict) -> 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": [],
             }
             body = _build_body(name, summary, cluster_issues, issues_by_num)
             write_file(path, meta, body)
             print(f"  ✓ {slug}.md created ({len(cluster_issues)} issues)")
+            if is_shared_route:
+                print("  ↑ shared — commit + push to share with teammates.")
             created += 1
 
     print()
@@ -208,6 +264,26 @@ def _apply(cfg: dict) -> 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/handoff.py

@@ -13,12 +13,13 @@ import subprocess
 from datetime import datetime, timedelta
 
 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.frontmatter import write_file
 from lib.session_log import append_session_log, SESSION_LOG_HEADER
 from lib.git_state import (
     has_uncommitted, current_branch, parse_iso_timestamp,
     gap_seconds_to_label, uncommitted_file_count, commits_ahead,
+    is_safe_ref, GIT_TIMEOUT,
 )
 from lib.github_state import fetch_issues, state_to_status_label, extract_priority, short_milestone
 from lib.status_table import update_row_status, sync_missing_rows, find_canonical_status_tables, ISSUE_NUM_RE
@@ -28,7 +29,7 @@ from lib.prompts import prompt_lines, parse_flags, prompt_input
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next"})
+    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next", "--repo"})
     interactive = flags.get("--interactive", False) or flags.get("-i", False)
     auto_next = flags.get("--auto-next", False)
 
@@ -54,6 +55,14 @@ def run(args: list[str]) -> int:
             return 2
 
     track_arg = positional[0] if positional else None
+    repo_qualifier = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    # Support <track>@<repo> syntax in positional
+    if track_arg:
+        name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+        track_arg = name_from_arg
+        if repo_from_arg:
+            repo_qualifier = repo_from_arg
 
     try:
         cfg = load_config()
@@ -62,7 +71,11 @@ def run(args: list[str]) -> int:
         return 1
 
     tracks = discover_tracks(cfg)
-    track = _resolve_track(tracks, track_arg)
+    try:
+        track = _resolve_track(tracks, track_arg, repo_qualifier=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
     if not track:
         return 1
 
@@ -254,9 +267,9 @@ def _check_next_up_collisions(track, proposed: list[int], cfg: dict) -> bool:
     return answer in ("y", "yes")
 
 
-def _resolve_track(tracks, track_arg):
+def _resolve_track(tracks, track_arg, repo_qualifier=None):
     if track_arg:
-        track = find_track_by_name(track_arg, tracks)
+        track = find_track_by_name(track_arg, tracks, repo=repo_qualifier)
         if not track:
             print(f"No track matching '{track_arg}'.")
         return track
@@ -502,12 +515,20 @@ def _recent_commits(track, since_dt) -> list[dict]:
 
     if branches:
         for b in branches:
-            proc = subprocess.run(
-                ["git", "-C", str(track.local_path), "log", b,
-                 f"--since={since_iso}",
-                 "--pretty=format:%H|%s|%cI"],
-                capture_output=True, text=True,
-            )
+            # A branch name from frontmatter is passed as a positional rev; a
+            # dash-led value (e.g. `--output=/path`) would be read by git as an
+            # option → arbitrary-file write. Reject before use (#192).
+            if not is_safe_ref(str(b)):
+                continue
+            try:
+                proc = subprocess.run(
+                    ["git", "-C", str(track.local_path), "log", b,
+                     f"--since={since_iso}",
+                     "--pretty=format:%H|%s|%cI"],
+                    capture_output=True, text=True, timeout=GIT_TIMEOUT,
+                )
+            except (subprocess.TimeoutExpired, OSError):
+                continue
             if proc.returncode != 0 or not proc.stdout.strip():
                 continue
             for line in proc.stdout.strip().split("\n"):

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

@@ -14,10 +14,14 @@ is per-repo, so:
     that repo;
   - when --repo is absent and config has multiple repos, it's skipped cleanly
     (rather than letting duplicates exit non-zero on the ambiguous case).
+
+Pass --timeout=N to set the gh subprocess timeout for the duplicates step
+(default 30s).
 """
 from commands import refresh_md, reconcile, duplicates
 from lib.config import load_config, ConfigError
 from lib.prompts import parse_flags
+import time
 
 
 def _resolve_repo_folder(repo_key: str, cfg: dict):
@@ -35,16 +39,28 @@ def _resolve_repo_folder(repo_key: str, cfg: dict):
 
 
 def run(args: list[str]) -> int:
-    flags, _ = parse_flags(args, {"--yes", "--no-duplicates", "--repo"})
+    flags, _ = parse_flags(args, {"--yes", "--no-duplicates", "--repo", "--timeout"})
     skip_dups = flags.get("--no-duplicates", False)
     yes = flags.get("--yes", False)
     repo_key = flags.get("--repo")
     if repo_key is True:
-        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>]")
+        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>] [--timeout=N]")
+        return 2
+
+    gh_timeout = None
+    raw_timeout = flags.get("--timeout")
+    if raw_timeout is not None and raw_timeout is not True:
+        try:
+            gh_timeout = int(raw_timeout)
+        except ValueError:
+            print(f"WARNING: invalid --timeout value '{raw_timeout}'; using default")
+    elif raw_timeout is True:
+        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>] [--timeout=N]")
         return 2
 
     scope_label = f" --repo={repo_key}" if repo_key else " --all"
 
+    t0 = time.time()
     print("=" * 60)
     print(f"WEEKLY HYGIENE — step 1 of 3: refresh-md{scope_label}")
     print("=" * 60)
@@ -54,21 +70,27 @@ def run(args: list[str]) -> int:
     rc = refresh_md.run(refresh_args)
     if rc != 0:
         print(f"\n⚠ refresh-md exited with code {rc}; continuing.")
+    print(f"  (step 1/3 done in {time.time() - t0:.1f}s)")
 
+    t1 = time.time()
     print()
     print("=" * 60)
     print(f"WEEKLY HYGIENE — step 2 of 3: reconcile{scope_label}")
     print("=" * 60)
     reconcile_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
+    if yes:
+        reconcile_args.append("--yes")
     rc = reconcile.run(reconcile_args)
     if rc != 0:
         print(f"\n⚠ reconcile exited with code {rc}; continuing.")
+    print(f"  (step 2/3 done in {time.time() - t1:.1f}s)")
 
     if skip_dups:
         print()
         print("(skipping duplicates per --no-duplicates)")
         return 0
 
+    t2 = time.time()
     print()
     print("=" * 60)
     print("WEEKLY HYGIENE — step 3 of 3: duplicates")
@@ -94,11 +116,15 @@ def run(args: list[str]) -> int:
         return 0
     # else: 0 or 1 repos → duplicates handles both (errors / single-repo auto-pick)
 
+    if gh_timeout is not None:
+        dupes_args.append(f"--timeout={gh_timeout}")
+
     rc = duplicates.run(dupes_args)
     if rc != 0:
         print(f"\n⚠ duplicates exited with code {rc}.")
+    print(f"  (step 3/3 done in {time.time() - t2:.1f}s)")
 
     print()
-    print("✓ Weekly hygiene complete. Review the duplicate candidates above and "
+    print(f"✓ Weekly hygiene complete ({time.time() - t0:.1f}s total). Review the duplicate candidates above and "
           "consolidate any real dupes via `gh issue close`.")
     return 0

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

@@ -3,6 +3,7 @@ import json
 import re
 from datetime import datetime
 from pathlib import Path
+from typing import Optional
 
 from lib.config import load_config, ConfigError, resolve_github_for_folder
 from lib.frontmatter import parse_file, write_file
@@ -12,6 +13,21 @@ from lib.write_guard import needs_confirm, make_token, valid_token
 _VALID_PRIORITIES = {"P0", "P1", "P2", "P3"}
 
 
+def _find_repo_for_shared_path(path: Path, cfg: dict) -> Optional[str]:
+    """If path is inside a .work-plan/ dir, find the configured github repo for that clone."""
+    # Walk up the path looking for a .work-plan ancestor
+    for parent in path.parents:
+        if parent.name == ".work-plan":
+            clone_root = parent.parent
+            for folder, entry in cfg.get("repos", {}).items():
+                if entry.get("local"):
+                    local = Path(entry["local"]).expanduser().resolve()
+                    if local == clone_root.resolve():
+                        return entry.get("github")
+            return None  # In .work-plan/ but not registered
+    return None  # Not in a .work-plan/
+
+
 def run(args: list[str]) -> int:
     flags, positional = parse_flags(args, {"--priority", "--milestone", "--confirm"})
 
@@ -37,13 +53,37 @@ def run(args: list[str]) -> int:
 
     slug = re.sub(r"[^a-z0-9-]+", "-", path.stem.lower()).strip("-")
 
-    notes_root = Path(cfg["notes_root"])
-    try:
-        rel = path.relative_to(notes_root)
-        folder = rel.parts[0] if len(rel.parts) > 1 else None
-    except ValueError:
+    # Detect if this path is inside a .work-plan/ shared directory
+    is_shared = ".work-plan" in path.parts
+    tier = "shared" if is_shared else None
+
+    if is_shared:
+        repo = _find_repo_for_shared_path(path, cfg)
+        if repo is None:
+            print(
+                "ERROR: path is inside a .work-plan/ directory but its repo isn't"
+                " registered in config — run init-repo first"
+            )
+            return 1
         folder = None
-    repo = resolve_github_for_folder(folder, cfg) if folder else None
+    else:
+        # Containment guard (#195): a non-shared target MUST live under
+        # notes_root. Without this, `init /etc/anything` (any user-writable
+        # file with no frontmatter) would get frontmatter prepended via
+        # write_file, clobbering it. `path` is already resolved; resolve
+        # notes_root too so the comparison is symlink/relative-safe.
+        notes_root = Path(cfg["notes_root"]).expanduser().resolve()
+        try:
+            rel = path.relative_to(notes_root)
+        except ValueError:
+            print(
+                f"ERROR: {path} is not inside notes_root ({notes_root}) or a"
+                " registered .work-plan/ directory — refusing to write"
+                " frontmatter outside the tracked tree."
+            )
+            return 1
+        folder = rel.parts[0] if len(rel.parts) > 1 else None
+        repo = resolve_github_for_folder(folder, cfg) if folder else None
 
     issue_nums = sorted(set(int(m) for m in re.findall(r"#(\d+)", body)))
 
@@ -79,6 +119,8 @@ def run(args: list[str]) -> int:
     print(f"Initializing: {path.name}")
     print(f"  track: {slug}")
     print(f"  repo: {repo or '(unknown — will set TBD)'}")
+    if tier == "shared":
+        print("  tier: shared")
     print(f"  issues found in body: {issue_nums or '(none)'}")
 
     now = datetime.now().strftime("%Y-%m-%dT%H:%M")
@@ -87,7 +129,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/init_repo.py

@@ -3,14 +3,53 @@
 Non-interactive: --github is required; --local is optional (no prompts).
 """
 import json
+import os
 import re
 import subprocess
 from pathlib import Path
 
-from lib.config import load_config, ConfigError, DEFAULT_CONFIG_PATH
+from lib.config import load_config, ConfigError, DEFAULT_CONFIG_PATH, is_valid_git_repo
 from lib.prompts import parse_flags
 
 
+def _count_shared_tracks(work_plan_dir: Path) -> int:
+    """Count eligible .md files in a .work-plan/ directory.
+
+    Excludes: README.md, dotfiles, and anything inside archive/.
+    """
+    count = 0
+    for p in work_plan_dir.iterdir():
+        if p.is_dir():
+            continue
+        if p.name.startswith("."):
+            continue
+        if p.name.lower() == "readme.md":
+            continue
+        if p.suffix == ".md":
+            count += 1
+    return count
+
+
+def _report_shared_tracks(local_path: "Path | None") -> None:
+    """Print a status line about shared tracks found in .work-plan/ (if any).
+
+    If local_path is None, not a valid git repo, or has no .work-plan/ dir,
+    prints the registration-only fallback message instead.
+    """
+    if local_path is None or not is_valid_git_repo(local_path):
+        print()
+        print("ℹ No valid local clone provided — registered for future use.")
+        print("  Run 'work-plan init-repo <key> --local=<path>' to add the clone path later.")
+        return
+    work_plan_dir = local_path / ".work-plan"
+    if work_plan_dir.is_dir():
+        n = _count_shared_tracks(work_plan_dir)
+        print(
+            f"ℹ Found {n} shared track(s) in {work_plan_dir}/"
+            " — they'll appear after 'work-plan brief'."
+        )
+
+
 def run(args: list[str]) -> int:
     flags, positional = parse_flags(args, {"--github", "--local"})
     if not positional:
@@ -45,6 +84,7 @@ def run(args: list[str]) -> int:
 
     # --local is optional; if absent, skip (no prompt)
     local = flags.get("--local") or None
+    local_path = None
     if local:
         local_path = Path(local).expanduser()
         if not local_path.exists():
@@ -67,15 +107,23 @@ def run(args: list[str]) -> int:
     print(f"  ├── archive/shipped/")
     print(f"  └── archive/abandoned/")
 
+    # Detect existing shared tracks in .work-plan/ inside the local clone
+    _report_shared_tracks(local_path)
+
     repo_block = {"github": github}
     if local:
         repo_block["local"] = local
 
-    yq_expr = f'.repos.{key} = {json.dumps(repo_block)}'
+    # `key` is validated against ^[a-z][a-z0-9-]*$ above, so it's safe in the yq
+    # path. The repo block is passed as an OPAQUE env value via env() (parsed as
+    # YAML/JSON) rather than interpolated into the expression — uniform with the
+    # strenv() hardening in set-notes-root (#196).
+    env = {**os.environ, "WP_REPO_BLOCK": json.dumps(repo_block)}
+    yq_expr = f".repos.{key} = env(WP_REPO_BLOCK)"
     try:
         subprocess.run(
             ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
-            check=True, capture_output=True, text=True,
+            check=True, capture_output=True, text=True, env=env,
         )
     except subprocess.CalledProcessError as e:
         print(f"ERROR: yq failed to update config: {e.stderr}")

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

@@ -1,10 +1,22 @@
 """list subcommand."""
 from lib.config import load_config, ConfigError
-from lib.tracks import discover_tracks, discover_archived_tracks
+from lib.tracks import (
+    discover_tracks, discover_archived_tracks,
+    priority_rank, recency_sort_key,
+)
+from lib.prompts import parse_flags
+
+_VALID_SORTS = ("recent", "priority")
 
 
 def run(args: list[str]) -> int:
-    show_all = "--all" in args
+    flags, _ = parse_flags(args, {"--all", "--sort"})
+    show_all = "--all" in flags
+    sort_mode = flags.get("--sort")
+    if sort_mode is True or (sort_mode and sort_mode not in _VALID_SORTS):
+        print(f"usage: work_plan.py list [--all] [--sort={'|'.join(_VALID_SORTS)}]")
+        return 2
+
     try:
         cfg = load_config()
     except ConfigError as e:
@@ -16,17 +28,19 @@ def run(args: list[str]) -> int:
         print(f"No tracks found under {cfg['notes_root']}")
         return 0
 
+    tracks = _sort_tracks(tracks, sort_mode)
+
     print(f"Tracks under {cfg['notes_root']}:\n")
     for t in tracks:
         status = t.meta.get("status", "(no frontmatter)")
         priority = t.meta.get("launch_priority", "—")
         repo = t.repo or "(no repo)"
-        flags = []
+        flags_out = []
         if t.needs_init:
-            flags.append("NEEDS INIT")
+            flags_out.append("NEEDS INIT")
         if t.needs_filing:
-            flags.append("NEEDS FILING")
-        flag_str = f" [{', '.join(flags)}]" if flags else ""
+            flags_out.append("NEEDS FILING")
+        flag_str = f" [{', '.join(flags_out)}]" if flags_out else ""
         print(f"  {t.name:30}  {status:14}  {priority:3}  {repo}{flag_str}")
 
     if show_all:
@@ -37,3 +51,17 @@ def run(args: list[str]) -> int:
                 end_state = a.meta.get("status", "?")
                 print(f"  {a.name:30}  {end_state:14}  {a.repo or '(no repo)'}")
     return 0
+
+
+def _sort_tracks(tracks: list, sort_mode):
+    """Order active tracks per --sort. None preserves discovery order.
+
+    - "recent": by last_touched descending (missing last_touched sorts last).
+    - "priority": by launch_priority ascending (P0→P3, then missing/other),
+      with last_touched recency as tiebreaker.
+    """
+    if sort_mode == "recent":
+        return sorted(tracks, key=lambda t: recency_sort_key(t.meta))
+    if sort_mode == "priority":
+        return sorted(tracks, key=lambda t: (priority_rank(t.meta), recency_sort_key(t.meta)))
+    return tracks