@stylusnexus/work-plan 2026.6.14 → 2026.6.15

package/README.md

@@ -108,6 +108,7 @@ flowchart TB
   - `handoff <track> --set-next 4167,4148` — explicit numbers when you know exactly which issues are next.
   - Free-form via Claude in your agent session, which can review project memory and write a curated list back. The two `--*-next` flags are the no-LLM paths.
   - For tracks where you don't want to bother curating at all, set `next_up_auto: true` in the track's frontmatter — `brief` will then derive the list live each invocation, ignoring whatever's stored.
+  - **Ranking presets** — when `next_up_auto: true` is on, the default ranking is `flow` (milestone → dependency → priority → recency). Override per-track with `set-next-up <track> --preset=<name>`, or set `next_up_default: <name>` in your config for a global fallback. Named presets: `flow` (the default), `priority-driven` (priority first, no milestone bias — good for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work). Custom criterion order: `set-next-up <track> --order=aging,priority,dependency`. Clear a track's override with `--clear`.
 - **Weekly** → `hygiene` runs `refresh-md --all` + `reconcile --all` + `duplicates` in sequence to keep status icons, GitHub labels, and dedup state honest.
 
 > **When should I run `refresh-md`?** Any time you close or merge issues and want the track body to reflect the new state. `handoff` rewrites the status table for one track on every run, but `brief` reads GitHub live without writing anything back — so a track you haven't `handoff`'d recently stays stale on disk. `refresh-md <track>` (or **Sync Issue States from GitHub** in VS Code) fixes that on-demand; `hygiene` sweeps all tracks weekly.
@@ -522,6 +523,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `remove-repo <key>` | Unregister a repo: delete its block from your config. **Config-only** — the notes folder, any tracks, and the local clone are left untouched (a notes folder or tracks that referenced it are now orphaned and can be removed by hand). Completes the add/update/remove trio with `init-repo`. |
 | `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. |
 | `rename-track <old-slug \| old@repo> <new-slug> [--repo=<key>] [--fix-refs] [--commit]` | Rename an active track's slug: moves its `.md` file and updates the frontmatter `track` field + `last_touched`. Validates `<new-slug>` like `new-track` and rejects a name already taken in the same repo/tier. For shared tracks, `--commit` stages + commits the move (otherwise it prints a "commit to share" hint). `--fix-refs` rewrites sibling tracks' `depends_on` that reference the old slug; without it they're just warned about. Archived tracks are immutable. Public-repo gated. |
+| `set-next-up <track> (--preset=<name> \| --order=a,b,c \| --clear) [--repo=<key>] [--confirm=<token>]` | Configure the ranking preset used when `next_up_auto: true` computes a suggestion. `--preset` sets a named preset: `flow` (default — milestone → dependency → priority → recency), `priority-driven` (priority first, ignores milestone bias, for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work), or `custom` (requires `--order`). `--order=a,b,c` sets a custom comma-separated criterion list (`milestone`, `dependency`, `priority`, `recency`, `aging`). `--clear` reverts to the global `next_up_default` config or the default `flow`. Writes `next_up_order` into the track's frontmatter; does NOT touch the `next_up` issue-list. Global default: add `next_up_default: <preset>` to `~/.claude/work-plan/config.yml`. Public-repo gated. |
 | `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. |
 | `notes-vcs <init\|enable\|disable\|status\|undo> [<sha>] [--no-enable] [--json]` | Opt-in **local** version control for the private `notes_root` tier — history/undo for tracks on your machine, never pushed. `init` git-inits `notes_root` as a personal repo (baseline commit of existing tracks) and turns on auto-commit (`--no-enable` skips that). For safety it **refuses** a `notes_root` that already has a git remote or is a repo work-plan didn't create. When on, every track-mutating command (`slot`/`group`/`handoff`/`close`/`set`/…) commits **only the files it changed** (pre-existing uncommitted edits are left alone) as an undoable commit. The shared tier is unaffected — it's versioned by its own repo. `status` shows whether `notes_root` is a repo, whether auto-commit is on, and the last commit (`--json` for the machine shape the VS Code viewer polls). `undo [<sha>]` reverts a commit (default HEAD) — reverses the last edit. |
 | `push-track <track\|track@repo> [--repo=<key>] [--no-push] [--confirm=<token>]` | **Promote a private track to the shared tier and publish it** (#306). Moves the track's `.md` from `notes_root` into the repo's `.work-plan/` (on its `plan_branch`, via a worktree), removes the private copy so it isn't duplicated, commits to the plan branch, and pushes — unless `--no-push`. Tier is derived from location, so this is a file move, not a frontmatter edit. Requires a local clone + a configured `plan_branch` (else hints `plan-branch init`). Pushing to a **public** repo makes the track world-visible → confirm-token gated. |

package/VERSION

@@ -1 +1 @@
-2026.06.14+ef58902
+2026.06.15+d52d670

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.14",
+  "version": "2026.6.15",
   "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/brief.py

@@ -17,7 +17,7 @@ from lib.git_state import (
 from lib.in_progress import issue_in_progress
 from lib.closure import compute_signals, is_closure_ready
 from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
-from lib.next_up import suggest_next_up
+from lib.next_up import suggest_next_up, resolve_next_up_order
 from lib.drift import detect_drift
 from lib.render import time_aware_framing, render_track_row, render_archived_reopen
 
@@ -121,15 +121,22 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
     # for display purposes — useful for tracks where you don't want to
     # hand-curate but still want a sensible "what's next" surfaced.
     track_milestone = meta.get("milestone_alignment") or None
+    hot_nums = hot_issue_numbers(local) if local else set()
     if meta.get("next_up_auto") and issues:
         blocker_nums = meta.get("blockers") or []
-        next_up_nums = suggest_next_up(issues, blocker_nums, track_milestone=track_milestone)
+        in_progress_set = {i["number"] for i in issues if issue_in_progress(i, hot_nums)}
+        _, order = resolve_next_up_order(meta, cfg.get("next_up_default"))
+        next_up_nums = suggest_next_up(
+            issues, blocker_nums,
+            track_milestone=track_milestone,
+            in_progress_nums=in_progress_set,
+            order=order,
+        )
     else:
         next_up_nums = stored_next_up
 
     next_up_items = []
     next_up_closed_count = 0
-    hot_nums = hot_issue_numbers(local) if local else set()
     for num in next_up_nums:
         i = issues_by_num.get(num)
         if not i:

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

@@ -140,13 +140,15 @@ def run(args: list[str]) -> int:
             if nums:
                 hot_by_track[(t.repo, t.name)] = nums
 
+    next_up_default = cfg.get("next_up_default")
     now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
     print(json.dumps(
         build_export(tracks, issues_by_track, visibility, now,
                      untracked_by_repo=untracked_by_repo,
                      config_repos=config_repos,
                      plan_by_track=plan_by_track,
-                     hot_by_track=hot_by_track),
+                     hot_by_track=hot_by_track,
+                     next_up_default=next_up_default),
         indent=2,
     ))
     return 0

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

@@ -19,12 +19,13 @@ 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,
+    is_safe_ref, GIT_TIMEOUT, hot_issue_numbers,
 )
 from lib.github_state import fetch_issues, state_to_status_label, extract_priority, short_milestone
+from lib.in_progress import issue_in_progress
 from lib.status_table import update_row_status, sync_missing_rows, find_canonical_status_tables, ISSUE_NUM_RE
 from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
-from lib.next_up import suggest_next_up
+from lib.next_up import suggest_next_up, resolve_next_up_order
 from lib.prompts import prompt_lines, parse_flags, prompt_input
 
 
@@ -152,7 +153,15 @@ def _apply_auto_next(track, cfg: dict) -> int:
     issues = fetch_issues(track.repo, issue_nums)
     blocker_nums = track.meta.get("blockers") or []
     track_milestone = track.meta.get("milestone_alignment") or None
-    raw_suggestion = suggest_next_up(issues, blocker_nums, track_milestone=track_milestone)
+    hot_nums = hot_issue_numbers(track.local_path) if track.local_path else set()
+    in_progress_set = {i["number"] for i in issues if issue_in_progress(i, hot_nums)}
+    _, order = resolve_next_up_order(track.meta, cfg.get("next_up_default"))
+    raw_suggestion = suggest_next_up(
+        issues, blocker_nums,
+        track_milestone=track_milestone,
+        in_progress_nums=in_progress_set,
+        order=order,
+    )
     if not raw_suggestion:
         print(f"No open, non-blocker issues for {track.name}; next_up unchanged.")
         return 0

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

@@ -0,0 +1,154 @@
+"""set-next-up subcommand — guarded edit of a track's next_up ranking preset.
+
+Usage:
+  work_plan.py set-next-up <track> [--repo=<key>] (--preset=<name> | --order=a,b,c | --clear) [--confirm=<token>]
+
+Writes `next_up_order` into the track's frontmatter. Does NOT touch the
+`next_up` issue-list key.
+
+Public-repo gated: without --confirm it prints {needs_confirm, reason, token}
+and makes no change. The VS Code extension surfaces that as a modal then
+re-invokes with --confirm=<token>.
+"""
+import json
+import sys
+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
+from lib.next_up import CRITERIA, PRESETS
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--confirm", "--repo", "--clear", "--preset", "--order"}
+    )
+    if not positional:
+        print(
+            "usage: work_plan.py set-next-up <track> "
+            "(--preset=<name> | --order=a,b,c | --clear) "
+            "[--repo=<key>] [--confirm=<token>]"
+        )
+        return 2
+
+    track_arg = positional[0]
+    name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+    name = name_from_arg
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+
+    clear = bool(flags.get("--clear"))
+    preset_flag = flags.get("--preset") if flags.get("--preset") is not True else None
+    order_flag = flags.get("--order") if flags.get("--order") is not True else None
+
+    # Must have at least one of --preset, --order, or --clear
+    if not clear and preset_flag is None and order_flag is None:
+        print(
+            "ERROR: specify --preset=<name>, --order=a,b,c, or --clear",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Validate preset name
+    if preset_flag is not None:
+        valid_presets = set(PRESETS.keys()) | {"custom"}
+        if preset_flag not in valid_presets:
+            print(
+                f"ERROR: unknown preset {preset_flag!r} "
+                f"(allowed: {sorted(valid_presets)})",
+                file=sys.stderr,
+            )
+            return 2
+        # 'custom' requires --order
+        if preset_flag == "custom" and order_flag is None:
+            print(
+                "ERROR: --preset=custom requires --order=<criteria>",
+                file=sys.stderr,
+            )
+            return 2
+
+    # Validate order criteria
+    order_list = None
+    if order_flag is not None:
+        raw_criteria = [c.strip() for c in order_flag.split(",") if c.strip()]
+        invalid = [c for c in raw_criteria if c not in CRITERIA]
+        if invalid:
+            print(
+                f"ERROR: unknown criteria {invalid!r} "
+                f"(allowed: {list(CRITERIA)})",
+                file=sys.stderr,
+            )
+            return 2
+        if not raw_criteria:
+            print("ERROR: --order requires at least one criterion", file=sys.stderr)
+            return 2
+        order_list = raw_criteria
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    try:
+        track = find_track_by_name(name, discover_tracks(cfg), repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching {name!r}.")
+        return 1
+
+    # Public-repo confirm gate
+    confirm = flags.get("--confirm")
+    if (
+        track.repo
+        and needs_confirm(track.repo, cfg)
+        and not (isinstance(confirm, str) and valid_token(confirm, track.repo, track.name))
+    ):
+        print(
+            json.dumps(
+                {
+                    "needs_confirm": True,
+                    "reason": (
+                        f"{track.repo} is PUBLIC (or visibility unknown); "
+                        "edit will be written there."
+                    ),
+                    "token": make_token(track.repo, track.name),
+                }
+            )
+        )
+        return 0
+
+    if clear:
+        track.meta.pop("next_up_order", None)
+        write_file(track.path, track.meta, track.body)
+        print(f"✓ cleared next_up_order on {track.name}")
+        return 0
+
+    # Build the next_up_order mapping
+    if preset_flag == "custom" or (preset_flag is None and order_list is not None):
+        # Custom order (either explicit --preset=custom or bare --order)
+        nuo = {"preset": "custom", "order": order_list}
+    else:
+        # Named preset. A named preset supplies its own criterion order, so a
+        # co-supplied --order has no effect — warn (advisory, don't reject) so
+        # the user isn't surprised it was dropped.
+        nuo = {"preset": preset_flag}
+        if order_list is not None:
+            print(
+                f"WARN: --order is ignored when a named preset "
+                f"(--preset={preset_flag}) is given; use --preset=custom "
+                "to supply your own order.",
+                file=sys.stderr,
+            )
+
+    track.meta["next_up_order"] = nuo
+    write_file(track.path, track.meta, track.body)
+
+    if preset_flag and preset_flag != "custom":
+        print(f"✓ set next_up_order preset={preset_flag!r} on {track.name}")
+    elif order_list is not None:
+        print(f"✓ set next_up_order custom order={order_list!r} on {track.name}")
+    return 0

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

@@ -1,5 +1,6 @@
 """Build the versioned viewer export structure from tracks + fetched issues."""
 from lib.github_state import format_assignees, short_milestone
+from lib.next_up import resolve_next_up_order
 
 SCHEMA = 1
 
@@ -84,7 +85,8 @@ def normalize_issue(i: dict, in_progress: bool = False,
 
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None, config_repos=None,
-                 plan_by_track=None, hot_by_track=None) -> dict:
+                 plan_by_track=None, hot_by_track=None,
+                 next_up_default=None) -> dict:
     plan_by_track = plan_by_track or {}
     hot_by_track = hot_by_track or {}
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
@@ -110,6 +112,7 @@ def build_export(tracks, issues_by_track, visibility, now: str,
         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]
         track_path = getattr(t, "path", None)
+        next_up_preset_name, _ = resolve_next_up_order(t.meta, next_up_default)
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
@@ -135,6 +138,8 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             # null when the track declares no `plan:`. `{rel, resolved:false}` when
             # the link can't be resolved (no local clone / file absent).
             "plan": plan_by_track.get(t.name),
+            # Effective next_up ranking preset for this track (#326 Phase 2).
+            "next_up_preset": next_up_preset_name,
         })
     out["untracked"] = [
         {"repo": repo, "issues": [normalize_issue(r) for r in rows]}

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

@@ -139,28 +139,67 @@ def branch_in_progress(branch_name: str, repo_path: Path) -> bool:
 _BRANCH_ISSUE_RE = re.compile(r"^(?:feat|fix)/(\d+)-")
 
 
-def hot_issue_numbers(repo_path: Path) -> set:
-    """Issue numbers with a 'hot' branch in `repo_path`.
+# Per-process memo for hot_issue_numbers, keyed by resolved repo path. A single
+# export/brief/orient run calls hot_issue_numbers once per track, but many tracks
+# share one clone (e.g. ~25 CritForge tracks → one checkout). Live git state can't
+# change mid-run, so caching by resolved path turns an O(tracks) rescan into
+# O(distinct clones). The CLI is one-shot, so the cache dies with the process;
+# tests reset it via _reset_hot_cache(). (#257 follow-up: pre-memo this was
+# ~40s × 25 tracks ≈ 16min for CritForge on every VS Code reload.)
+_HOT_CACHE: dict = {}
+
+
+def _reset_hot_cache() -> None:
+    """Clear the hot_issue_numbers memo (test hook; not used in production)."""
+    _HOT_CACHE.clear()
 
-    Enumerates local branches with `git branch --format=%(refname:short)` (the
-    --format is load-bearing: plain `git branch` prefixes lines with `  `/`* `/`+ `,
-    which would defeat the anchored regex), maps each `feat/<n>-`/`fix/<n>-` name
-    to <n>, and keeps those whose branch is `branch_in_progress`.
 
-    Failure contract: if the enumeration call fails -> empty set. A per-branch heat
-    check that fails collapses to cold (that branch is simply not added). Never raises.
+def hot_issue_numbers(repo_path: Path) -> set:
+    """Issue numbers with a 'hot' (in-progress) feat/<n>-/fix/<n>- branch in `repo_path`.
+
+    A branch is hot when its tip was committed in the last 24h, OR it is the
+    checked-out branch with uncommitted changes. Enumerates every branch and its
+    tip commit time in ONE `git for-each-ref` call (the recency signal), then does
+    a single current-branch/uncommitted check — so the cost is O(1) git calls, not
+    O(branches). (Previously each of the N branches incurred ~4 git subprocesses
+    via branch_in_progress; on a clone with hundreds of feat/fix branches that was
+    tens of seconds per call.) Result is memoized per resolved path for the process.
+
+    Failure contract: any git enumeration failure -> empty set (not cached, so a
+    later call in the same run can still succeed). Never raises.
     """
     if not repo_path or not Path(repo_path).exists():
         return set()
-    proc = _git(repo_path, "branch", "--format=%(refname:short)", "--list")
+    key = str(Path(repo_path).resolve())
+    cached = _HOT_CACHE.get(key)
+    if cached is not None:
+        return cached
+    proc = _git(repo_path, "for-each-ref", "refs/heads",
+                "--format=%(refname:short)%09%(committerdate:unix)")
     if proc is None or proc.returncode != 0:
         return set()
-    out = set()
+    cutoff = (datetime.now() - timedelta(hours=24)).timestamp()
+    hot = set()
+    candidates: dict = {}  # feat/fix branch name -> issue number
     for line in proc.stdout.splitlines():
-        m = _BRANCH_ISSUE_RE.match(line.strip())
-        if m and branch_in_progress(line.strip(), repo_path):
-            out.add(int(m.group(1)))
-    return out
+        name, _tab, ts = line.strip().partition("\t")
+        m = _BRANCH_ISSUE_RE.match(name)
+        if not m:
+            continue
+        num = int(m.group(1))
+        candidates[name] = num
+        try:
+            if float(ts) >= cutoff:
+                hot.add(num)
+        except ValueError:
+            pass  # missing/odd committerdate -> not hot by recency
+    # Uncommitted-changes-on-the-checked-out-branch case: 2 git calls total,
+    # independent of branch count (mirrors branch_in_progress's first clause).
+    cur = current_branch(repo_path)
+    if cur in candidates and has_uncommitted(repo_path):
+        hot.add(candidates[cur])
+    _HOT_CACHE[key] = hot
+    return hot
 
 
 def last_commit_date(branch_name: str, repo_path: Path) -> Optional[datetime]:

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

@@ -1,9 +1,28 @@
 """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.
+Default sort policy (all filters/keys applied in this order):
+
+Eligibility (filter, in order):
+  1. Drop non-OPEN issues.
+  2. Drop issues whose number is in blocker_nums (manual track blockers).
+  3. Drop issues that have a non-empty `blocked_by` list — the dependency
+     gate — UNLESS the issue is in-progress (an in-progress issue is never
+     gated out; you're already working it).
+
+Sort key (lexicographic, ascending = comes first) over survivors:
+  1. in-progress: 0 if in-progress else 1  (in-progress floats to top)
+  2..N. the preset-configurable MIDDLE dimensions (see below)
+  last. issue number: ascending (deterministic final tiebreak)
+
+The in-progress prefix and the number tiebreak are ALWAYS-ON. The middle
+dimensions are configurable per track via the `order` param — a list of
+criterion names drawn from CRITERIA (`milestone`, `dependency`, `priority`,
+`recency`, and `aging` — oldest-first, for surfacing stalled work). Named
+bundles live in PRESETS (default `flow`, plus `priority-driven` and
+`backlog`); `resolve_next_up_order` maps a track's frontmatter / global config
+to an effective order. `order=None` falls back to PRESETS["flow"], which
+reproduces the historical fixed policy (milestone → -fan_out → priority →
+-recency).
 
 Used by:
 - `commands/handoff.py` — `--auto-next` flag prompts the user to apply
@@ -19,7 +38,7 @@ they go here.
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Iterable
+from typing import Iterable, Optional
 
 from lib.github_state import extract_priority, short_milestone
 
@@ -32,6 +51,17 @@ MILESTONE_ALIGNED = 0
 MILESTONE_OTHER = 1
 MILESTONE_NONE = 2
 
+# Available sort criteria and their named preset bundles.
+CRITERIA = ("milestone", "dependency", "priority", "recency", "aging")
+
+PRESETS = {
+    "flow":            ["milestone", "dependency", "priority", "recency"],
+    "priority-driven": ["priority", "dependency", "recency"],
+    "backlog":         ["aging", "priority"],
+}
+
+DEFAULT_PRESET = "flow"
+
 
 def _updated_unix(issue: dict) -> float:
     """Parse the gh-formatted updatedAt field to a unix timestamp.
@@ -50,49 +80,142 @@ def _updated_unix(issue: dict) -> float:
         return 0.0
 
 
+def _fan_out(issue: dict) -> int:
+    """Return the number of open blocking edges this issue unblocks.
+
+    A higher value means merging this issue unblocks more downstream work.
+    Uses `.get(...) or []` so a missing key is treated as zero fan-out.
+    """
+    return len(issue.get("blocking") or [])
+
+
+def _criterion_scalar(criterion: str, issue: dict,
+                       track_milestone: Optional[str]) -> float:
+    """Return a single ascending sort scalar for one criterion.
+
+    Lower value = ranks first (since we sort ascending).
+    Unknown criterion names return 0.0 (neutral; caller should skip them).
+    """
+    if criterion == "milestone":
+        ms = short_milestone(issue.get("milestone"))
+        if not ms:
+            return float(MILESTONE_NONE)
+        if track_milestone and ms == track_milestone:
+            return float(MILESTONE_ALIGNED)
+        return float(MILESTONE_OTHER)
+    if criterion == "dependency":
+        return float(-_fan_out(issue))
+    if criterion == "priority":
+        pri = extract_priority(issue.get("labels", []))
+        return float(PRIORITY_RANK.get(pri, 3))
+    if criterion == "recency":
+        return float(-_updated_unix(issue))
+    if criterion == "aging":
+        return float(_updated_unix(issue))  # ascending = oldest first
+    return 0.0  # unknown criterion — neutral
+
+
 def suggest_next_up(
     issues: list[dict],
-    blocker_nums: Iterable[int] | None = None,
+    blocker_nums: Optional[Iterable[int]] = None,
     n: int = DEFAULT_TOP_N,
-    track_milestone: str | None = None,
+    track_milestone: Optional[str] = None,
+    in_progress_nums: Optional[Iterable[int]] = None,
+    order: Optional[list[str]] = 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,...`.
+            number,state,labels,milestone,updatedAt,blocked_by,blocking,...`.
         blocker_nums: iterable of issue numbers to exclude (a track's
-            manually-flagged blockers).
+            manually-flagged blockers). These are ALWAYS excluded, even if
+            the issue is in-progress.
         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.
+            which in turn rank above items with no milestone.
+        in_progress_nums: optional set of issue numbers currently in-progress
+            (label or hot branch). In-progress issues float to the top of the
+            ranked list and are also exempt from the `blocked_by` gate — you
+            are already working them, so they must stay visible. When None
+            (or empty), no in-progress boost is applied.
+        order: optional list of criterion names (from CRITERIA) controlling
+            the sort dimensions after the in-progress prefix and before the
+            number tiebreak. None defaults to PRESETS[DEFAULT_PRESET] (="flow"),
+            producing identical results to Phase 1 behaviour. Unknown criterion
+            names in `order` are silently skipped (defensive).
 
     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))
+    in_progress = set(in_progress_nums or [])
+    # Resolve order: None → default preset; unknown names in list → skipped.
+    effective_order = order if order is not None else PRESETS[DEFAULT_PRESET]
+
+    candidates = []
+    for i in issues:
+        if str(i.get("state", "")).upper() != "OPEN":
+            continue
+        num = i.get("number")
+        # Manual blocker_nums always excluded — in-progress does NOT override.
+        if num in blockers:
+            continue
+        # Dependency gate: skip if blocked_by is non-empty, UNLESS in-progress.
+        if (i.get("blocked_by") or []) and num not in in_progress:
+            continue
+        candidates.append(i)
+
+    def sort_key(issue: dict) -> tuple:
+        num = issue.get("number")
+        in_prog_rank = 0 if num in in_progress else 1
+        criterion_scalars = tuple(
+            _criterion_scalar(c, issue, track_milestone)
+            for c in effective_order
+            if c in CRITERIA  # skip unknown criteria
+        )
+        return (in_prog_rank,) + criterion_scalars + (num,)
 
     candidates.sort(key=sort_key)
     return [i["number"] for i in candidates[:n]]
+
+
+def resolve_next_up_order(track_meta: dict,
+                          default_preset: Optional[str] = None) -> tuple:
+    """Return (effective_preset_name, order_list) for a track.
+
+    Resolution priority:
+    1. track frontmatter next_up_order.preset (or next_up_order.order if
+       preset=='custom')
+    2. global default_preset param
+    3. DEFAULT_PRESET ("flow")
+
+    Unknown preset names fall back to DEFAULT_PRESET.
+    'custom' preset uses track_meta['next_up_order']['order'] (validated
+    against CRITERIA; invalid/empty list → DEFAULT_PRESET's order).
+
+    IMPORTANT: reads from 'next_up_order' key (a mapping), NOT 'next_up'
+    (the issue-list).
+    """
+    nuo = track_meta.get("next_up_order")
+    if isinstance(nuo, dict):
+        preset = nuo.get("preset")
+        if preset == "custom":
+            raw_order = nuo.get("order") or []
+            # Validate: all entries must be in CRITERIA
+            valid = [c for c in raw_order if c in CRITERIA]
+            if valid:
+                return ("custom", valid)
+            # Invalid or empty custom order → fall through to default
+        elif preset in PRESETS:
+            return (preset, PRESETS[preset])
+        # Unknown preset name falls through to global default
+
+    # Global default
+    if default_preset and default_preset in PRESETS:
+        return (default_preset, PRESETS[default_preset])
+
+    return (DEFAULT_PRESET, PRESETS[DEFAULT_PRESET])