@stylusnexus/work-plan 2026.6.14-1 → 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+6579bf7
+2026.06.15+d52d670

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.14-1",
+  "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/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])

package/skills/work-plan/tests/test_export.py

@@ -35,6 +35,9 @@ class BuildExportTest(unittest.TestCase):
         self.assertEqual(t["blockers"], [9]); self.assertEqual(t["next_up"], [1])
         self.assertEqual(t["rollup"], {"open": 1, "closed": 1})
         self.assertEqual(t["issues"][0], {"number": 1, "title": "a", "state": "open", "assignee": "@eve", "milestone": None, "in_progress": False, "in_progress_label": False, "blocked_by": [], "blocking": []})
+        # Phase 2: next_up_preset must be present in every track
+        self.assertIn("next_up_preset", t)
+        self.assertEqual(t["next_up_preset"], "flow")  # default when no next_up_order in meta
         json.dumps(out)  # must be serializable
 
     def test_path_is_null_when_track_has_no_path(self):
@@ -459,6 +462,56 @@ class InProgressExportTest(unittest.TestCase):
         self.assertFalse(issue["in_progress_label"])  # no label present
 
 
+class BuildExportNextUpPresetTest(unittest.TestCase):
+    """Tests that build_export emits next_up_preset on each track (#326 Phase 2)."""
+
+    def _build(self, track_meta_override=None, next_up_default=None):
+        from types import SimpleNamespace
+        meta = {
+            "status": "active",
+            "launch_priority": "P2",
+            "milestone_alignment": "v1",
+            "blockers": [],
+            "next_up": [],
+            "depends_on": [],
+            "github": {"repo": "o/r", "issues": []},
+        }
+        if track_meta_override:
+            meta.update(track_meta_override)
+        t = SimpleNamespace(name="alpha", repo="o/r", tier="private",
+                            path=Path("/tmp/notes/alpha.md"), folder="myrepo",
+                            meta=meta)
+        out = build_export([t], {("o/r", "alpha"): []}, {"o/r": "PRIVATE"},
+                           now="2026-06-14T00:00", next_up_default=next_up_default)
+        return out["tracks"][0]
+
+    def test_next_up_preset_field_present(self):
+        """Export emits next_up_preset for each track."""
+        track = self._build()
+        self.assertIn("next_up_preset", track)
+
+    def test_next_up_preset_defaults_to_flow(self):
+        """Track with no next_up_order → next_up_preset == 'flow'."""
+        track = self._build()
+        self.assertEqual(track["next_up_preset"], "flow")
+
+    def test_next_up_preset_reflects_track_setting(self):
+        """Track with next_up_order: {preset: priority-driven} → next_up_preset == 'priority-driven'."""
+        track = self._build({"next_up_order": {"preset": "priority-driven"}})
+        self.assertEqual(track["next_up_preset"], "priority-driven")
+
+    def test_next_up_preset_uses_global_default(self):
+        """Track with no next_up_order + global next_up_default='backlog' → next_up_preset == 'backlog'."""
+        track = self._build(next_up_default="backlog")
+        self.assertEqual(track["next_up_preset"], "backlog")
+
+    def test_track_setting_overrides_global_default(self):
+        """Track-level next_up_order overrides the global next_up_default."""
+        track = self._build({"next_up_order": {"preset": "backlog"}},
+                            next_up_default="priority-driven")
+        self.assertEqual(track["next_up_preset"], "backlog")
+
+
 class BlockedByExportTest(unittest.TestCase):
     def _track(self, name, repo):
         from types import SimpleNamespace

package/skills/work-plan/tests/test_next_up.py

@@ -1,10 +1,11 @@
 """Tests for the next_up suggestion algorithm.
 
 Covers the priority + recency sort, blocker exclusion, closed-issue filter,
-top-N capping, and the `updatedAt`-missing fallback. The algorithm has one
-home (lib/next_up.py) shared by handoff's --auto-next flag and brief's
-next_up_auto: true frontmatter knob — so a regression here would surface
-in both commands.
+top-N capping, `updatedAt`-missing fallback, dependency gate (blocked_by),
+in-progress float, fan-out ranking, and the deterministic number tiebreak.
+The algorithm has one home (lib/next_up.py) shared by handoff's --auto-next
+flag and brief's next_up_auto: true frontmatter knob — so a regression here
+would surface in both commands.
 """
 import sys
 import unittest
@@ -13,19 +14,33 @@ from pathlib import Path
 SKILL_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(SKILL_ROOT))
 
-from lib.next_up import suggest_next_up
+from lib.next_up import suggest_next_up, resolve_next_up_order, PRESETS, DEFAULT_PRESET
 
 
 def _issue(num, *, state="OPEN", priority=None, updated="2026-01-01T00:00:00Z",
-           title="", milestone=None):
-    """Build a minimal issue dict matching gh's --json output."""
+           title="", milestone=None, blocked_by=None, blocking=None):
+    """Build a minimal issue dict matching gh's --json output.
+
+    blocked_by / blocking each accept a list of {number, repo, title} dicts
+    (OPEN-filtered, as delivered by github_state after #257).
+    """
     labels = [{"name": f"priority/{priority}"}] if priority else []
     ms_obj = {"title": milestone} if milestone else None
-    return {
+    issue = {
         "number": num, "state": state, "labels": labels,
         "updatedAt": updated, "title": title or f"issue #{num}",
         "milestone": ms_obj,
     }
+    if blocked_by is not None:
+        issue["blocked_by"] = blocked_by
+    if blocking is not None:
+        issue["blocking"] = blocking
+    return issue
+
+
+def _dep(num, repo="stylusnexus/demo"):
+    """Build a minimal dependency edge dict {number, repo, title}."""
+    return {"number": num, "repo": repo, "title": f"dep #{num}"}
 
 
 class SuggestNextUpTest(unittest.TestCase):
@@ -145,5 +160,263 @@ class SuggestNextUpTest(unittest.TestCase):
         self.assertEqual(result, [2, 1])  # parsable+newer wins; garbage trails
 
 
+class InProgressAndDependencyTest(unittest.TestCase):
+    """Phase 1 additions: dependency gate, in-progress float, fan-out, tiebreak."""
+
+    # ------------------------------------------------------------------
+    # in-progress float
+    # ------------------------------------------------------------------
+
+    def test_in_progress_floats_above_higher_priority(self):
+        """An in-progress P2 should sort above a non-in-progress P0."""
+        issues = [
+            _issue(1, priority="P0"),   # high priority, NOT in-progress
+            _issue(2, priority="P2"),   # lower priority, IS in-progress
+        ]
+        result = suggest_next_up(issues, [], in_progress_nums={2})
+        self.assertEqual(result[0], 2, "in-progress issue must float to top")
+        self.assertEqual(result[1], 1)
+
+    def test_in_progress_floats_above_milestone_aligned(self):
+        """In-progress with no milestone still beats milestone-aligned non-in-progress."""
+        issues = [
+            _issue(1, priority="P3", milestone="v1.0 — MVP"),  # aligned, not in-prog
+            _issue(2, priority="P3", milestone=None),           # no milestone, in-prog
+        ]
+        result = suggest_next_up(issues, [], track_milestone="v1.0",
+                                 in_progress_nums={2})
+        self.assertEqual(result[0], 2)
+
+    # ------------------------------------------------------------------
+    # dependency gate
+    # ------------------------------------------------------------------
+
+    def test_blocked_issue_excluded_from_candidates(self):
+        """An issue with a non-empty blocked_by list is gated out of the result."""
+        issues = [
+            _issue(1, priority="P0", blocked_by=[_dep(99)]),  # blocked — gated
+            _issue(2, priority="P1"),                          # open, unblocked
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertNotIn(1, result, "blocked issue must not appear")
+        self.assertIn(2, result)
+
+    def test_blocked_but_in_progress_stays_in_result(self):
+        """An in-progress issue is never gated out by blocked_by."""
+        issues = [
+            _issue(1, priority="P0", blocked_by=[_dep(99)]),  # blocked but in-progress
+            _issue(2, priority="P1"),
+        ]
+        result = suggest_next_up(issues, [], in_progress_nums={1})
+        self.assertIn(1, result, "in-progress issue must survive the blocked_by gate")
+
+    def test_empty_blocked_by_list_is_not_gated(self):
+        """An explicit empty blocked_by list is treated as unblocked."""
+        issues = [
+            _issue(1, priority="P0", blocked_by=[]),
+            _issue(2, priority="P1"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertIn(1, result, "empty blocked_by should not gate the issue")
+
+    def test_missing_blocked_by_key_is_not_gated(self):
+        """Issues without a blocked_by key at all pass through (backward-compat)."""
+        issues = [
+            _issue(1, priority="P0"),  # no blocked_by key
+            _issue(2, priority="P1"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertIn(1, result)
+
+    # ------------------------------------------------------------------
+    # fan-out ranking
+    # ------------------------------------------------------------------
+
+    def test_higher_fanout_ranks_above_higher_priority(self):
+        """Fan-out (unblocking count) outranks priority within same milestone bucket."""
+        issues = [
+            _issue(1, priority="P0",   # high priority, zero fan-out
+                   blocking=[]),
+            _issue(2, priority="P2",   # lower priority, high fan-out
+                   blocking=[_dep(10), _dep(11), _dep(12)]),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertEqual(result[0], 2, "fan-out beats priority")
+        self.assertEqual(result[1], 1)
+
+    def test_milestone_beats_fanout(self):
+        """Milestone alignment beats fan-out: aligned-zero-fanout > off-milestone-high-fanout."""
+        issues = [
+            _issue(1, priority="P2", milestone="v1.0 — MVP",   # aligned, no fan-out
+                   blocking=[]),
+            _issue(2, priority="P2", milestone="v2.0 — Beta",  # off-milestone, high fan-out
+                   blocking=[_dep(10), _dep(11), _dep(12)]),
+        ]
+        result = suggest_next_up(issues, [], track_milestone="v1.0")
+        self.assertEqual(result[0], 1, "milestone-aligned must beat high-fanout off-milestone")
+
+    def test_blocking_field_absent_treated_as_zero_fanout(self):
+        """Missing blocking key → fan-out = 0; does not crash."""
+        issues = [
+            _issue(1, priority="P1"),   # no blocking key
+            _issue(2, priority="P1", blocking=[_dep(10)]),  # fan-out=1
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertEqual(result[0], 2, "fan-out=1 beats fan-out=0")
+
+    # ------------------------------------------------------------------
+    # deterministic tiebreak
+    # ------------------------------------------------------------------
+
+    def test_number_tiebreak_when_all_else_equal(self):
+        """When every sort dimension ties, lower issue number wins."""
+        issues = [
+            _issue(30, priority="P1", updated="2026-01-01T00:00:00Z"),
+            _issue(10, priority="P1", updated="2026-01-01T00:00:00Z"),
+            _issue(20, priority="P1", updated="2026-01-01T00:00:00Z"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertEqual(result, [10, 20, 30])
+
+    # ------------------------------------------------------------------
+    # backward-compat
+    # ------------------------------------------------------------------
+
+    def test_no_in_progress_nums_does_not_crash(self):
+        """Calling without in_progress_nums must not raise; no in-progress boost applied."""
+        issues = [_issue(1, priority="P0"), _issue(2, priority="P1")]
+        result = suggest_next_up(issues, [])  # old call signature
+        self.assertEqual(result, [1, 2])
+
+    def test_blocked_by_excluded_without_in_progress_nums(self):
+        """Without in_progress_nums, blocked issues are gated out (no in-prog bypass)."""
+        issues = [
+            _issue(1, priority="P0", blocked_by=[_dep(99)]),
+            _issue(2, priority="P1"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertNotIn(1, result)
+        self.assertIn(2, result)
+
+    def test_manual_blocker_still_excluded(self):
+        """Manual blocker_nums exclusion is unaffected by the new in-progress param."""
+        issues = [
+            _issue(1, priority="P0"),
+            _issue(2, priority="P1"),
+        ]
+        result = suggest_next_up(issues, [1], in_progress_nums={1})
+        # in-progress does NOT override manual blocker_nums exclusion
+        self.assertNotIn(1, result)
+        self.assertIn(2, result)
+
+
+class PresetAndResolverTest(unittest.TestCase):
+    """Phase 2: preset ordering + resolver tests."""
+
+    # ------------------------------------------------------------------
+    # preset ordering
+    # ------------------------------------------------------------------
+
+    def test_flow_preset_equivalent_to_phase1_default(self):
+        """order=None and order=PRESETS['flow'] must produce identical results."""
+        issues = [
+            _issue(1, priority="P0", milestone="v1.0"),
+            _issue(2, priority="P2", updated="2026-04-30T00:00:00Z"),
+            _issue(3, priority="P1", milestone="v1.0", blocking=[_dep(5), _dep(6)]),
+        ]
+        result_none = suggest_next_up(issues, [], track_milestone="v1.0")
+        result_flow = suggest_next_up(issues, [], track_milestone="v1.0",
+                                      order=PRESETS["flow"])
+        self.assertEqual(result_none, result_flow,
+                         "order=None must be equivalent to order=PRESETS['flow']")
+
+    def test_priority_driven_ranks_p0_above_off_milestone(self):
+        """priority-driven: a P0 with no milestone beats a P3 on the track milestone."""
+        issues = [
+            _issue(1, priority="P0", milestone=None),
+            _issue(2, priority="P3", milestone="v0.4.0 — MVP"),
+        ]
+        result = suggest_next_up(issues, [], track_milestone="v0.4.0",
+                                 order=PRESETS["priority-driven"])
+        # With priority-driven, priority > milestone so P0 beats P3-on-milestone
+        self.assertEqual(result[0], 1,
+                         "P0 with no milestone must beat P3 on track milestone under priority-driven")
+
+    def test_backlog_puts_oldest_first(self):
+        """backlog preset: oldest issue (smallest timestamp) ranks above newer."""
+        issues = [
+            _issue(10, priority="P2", updated="2026-06-01T00:00:00Z"),  # newer
+            _issue(20, priority="P2", updated="2024-01-01T00:00:00Z"),  # older
+        ]
+        result = suggest_next_up(issues, [], order=PRESETS["backlog"])
+        self.assertEqual(result[0], 20,
+                         "backlog preset must surface oldest (most stalled) issue first")
+
+    def test_unknown_criterion_in_order_skipped(self):
+        """An order list with an unknown criterion must not crash; known ones still apply."""
+        issues = [
+            _issue(1, priority="P0"),
+            _issue(2, priority="P1"),
+        ]
+        # Should not raise; the unknown 'bogus' criterion is skipped
+        result = suggest_next_up(issues, [], order=["bogus", "priority", "recency"])
+        self.assertEqual(result[0], 1, "priority criterion must still sort correctly")
+        self.assertNotIn("bogus", result)  # just making sure it didn't error on str
+
+    # ------------------------------------------------------------------
+    # resolver
+    # ------------------------------------------------------------------
+
+    def test_resolve_next_up_order_uses_track_frontmatter(self):
+        """Track with next_up_order: {preset: priority-driven} → resolver returns that preset."""
+        meta = {"next_up_order": {"preset": "priority-driven"}}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, "priority-driven")
+        self.assertEqual(order, PRESETS["priority-driven"])
+
+    def test_resolve_next_up_order_falls_back_to_global_default(self):
+        """No track frontmatter → uses global default param."""
+        meta = {}
+        name, order = resolve_next_up_order(meta, default_preset="backlog")
+        self.assertEqual(name, "backlog")
+        self.assertEqual(order, PRESETS["backlog"])
+
+    def test_resolve_next_up_order_falls_back_to_default_preset(self):
+        """Neither track frontmatter nor global default → returns ('flow', PRESETS['flow'])."""
+        meta = {}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, DEFAULT_PRESET)
+        self.assertEqual(order, PRESETS[DEFAULT_PRESET])
+
+    def test_resolve_next_up_order_custom_uses_order_list(self):
+        """next_up_order: {preset: custom, order: [priority, recency]} → custom order used."""
+        meta = {"next_up_order": {"preset": "custom", "order": ["priority", "recency"]}}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, "custom")
+        self.assertEqual(order, ["priority", "recency"])
+
+    def test_resolve_next_up_order_unknown_preset_falls_back_to_flow(self):
+        """Track has next_up_order: {preset: nonexistent} → returns ('flow', PRESETS['flow'])."""
+        meta = {"next_up_order": {"preset": "nonexistent"}}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, DEFAULT_PRESET)
+        self.assertEqual(order, PRESETS[DEFAULT_PRESET])
+
+    def test_resolve_next_up_order_invalid_custom_order_falls_back(self):
+        """next_up_order: {preset: custom, order: [bogus]} → falls back to flow."""
+        meta = {"next_up_order": {"preset": "custom", "order": ["bogus"]}}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, DEFAULT_PRESET)
+        self.assertEqual(order, PRESETS[DEFAULT_PRESET])
+
+    def test_resolve_reads_next_up_order_not_next_up(self):
+        """Resolver reads 'next_up_order' key (a mapping), NOT 'next_up' (the issue-list)."""
+        # next_up is the issue list — should not affect the resolver
+        meta = {"next_up": [101, 102], "next_up_order": {"preset": "backlog"}}
+        name, order = resolve_next_up_order(meta)
+        self.assertEqual(name, "backlog")
+        self.assertEqual(order, PRESETS["backlog"])
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/tests/test_set_next_up.py

@@ -0,0 +1,201 @@
+# tests/test_set_next_up.py
+"""Tests for the set-next-up command.
+
+Mirrors test_set_field.py structure. Tests preset setting, custom order,
+clear, public-repo gating, and validation.
+"""
+import io
+import sys
+import unittest
+from contextlib import redirect_stdout, redirect_stderr
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import set_next_up
+from lib.write_guard import make_token
+
+
+def _t(name="ph", repo="o/r", meta=None):
+    base_meta = {"status": "active", "github": {"repo": repo}}
+    if meta is not None:
+        base_meta.update(meta)
+    return SimpleNamespace(
+        name=name,
+        repo=repo,
+        path=Path(f"/tmp/{name}.md"),
+        has_frontmatter=True,
+        meta=base_meta,
+        body="# b",
+    )
+
+
+def _drive(args, vis="PRIVATE", cfg=None, track=None):
+    base_cfg = {"notes_root": "/tmp"}
+    if cfg is not None:
+        base_cfg.update(cfg)
+    t = track if track is not None else _t()
+    with patch("commands.set_next_up.load_config", return_value=base_cfg), \
+         patch("commands.set_next_up.discover_tracks", return_value=[t]), \
+         patch("lib.write_guard.repo_visibility", return_value=vis), \
+         patch("commands.set_next_up.write_file") as mw:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = set_next_up.run(args)
+    return rc, mw, buf.getvalue()
+
+
+class SetNextUpTest(unittest.TestCase):
+
+    def test_set_preset_private(self):
+        """set-next-up ph --preset=priority-driven on private repo writes next_up_order."""
+        rc, mw, out = _drive(["ph", "--preset=priority-driven"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"], {"preset": "priority-driven"})
+
+    def test_set_order_custom(self):
+        """set-next-up ph --order=priority,recency writes next_up_order with preset=custom."""
+        rc, mw, out = _drive(["ph", "--order=priority,recency"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"], {"preset": "custom", "order": ["priority", "recency"]})
+
+    def test_clear_removes_key(self):
+        """set-next-up ph --clear with next_up_order in meta removes the key."""
+        t = _t(meta={"status": "active", "next_up_order": {"preset": "backlog"}})
+        rc, mw, out = _drive(["ph", "--clear"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_order", meta)
+
+    def test_public_blocks_without_confirm(self):
+        """PUBLIC repo without --confirm emits needs_confirm and does not write."""
+        rc, mw, out = _drive(["ph", "--preset=priority-driven"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_public_with_valid_confirm_writes(self):
+        """PUBLIC repo with valid --confirm token proceeds to write."""
+        tok = make_token("o/r", "ph")
+        rc, mw, out = _drive(["ph", "--preset=priority-driven", f"--confirm={tok}"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"], {"preset": "priority-driven"})
+
+    def test_rejects_invalid_preset(self):
+        """Unknown preset name → rc=2, no write."""
+        rc, mw, out = _drive(["ph", "--preset=nonexistent"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_rejects_invalid_criteria(self):
+        """--order with an invalid criterion (bogus) → rc=2, no write."""
+        rc, mw, out = _drive(["ph", "--order=bogus,milestone"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_custom_preset_requires_order(self):
+        """--preset=custom without --order → rc=2, no write."""
+        rc, mw, out = _drive(["ph", "--preset=custom"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_requires_preset_or_order_or_clear(self):
+        """No flags at all → rc=2."""
+        rc, mw, out = _drive(["ph"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_set_preset_flow(self):
+        """--preset=flow is valid and writes correctly."""
+        rc, mw, out = _drive(["ph", "--preset=flow"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"], {"preset": "flow"})
+
+    def test_set_preset_backlog(self):
+        """--preset=backlog is valid and writes correctly."""
+        rc, mw, out = _drive(["ph", "--preset=backlog"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"], {"preset": "backlog"})
+
+    def test_custom_with_order_all_criteria(self):
+        """--preset=custom --order=milestone,dependency,priority,recency,aging is valid."""
+        rc, mw, out = _drive(["ph", "--preset=custom",
+                               "--order=milestone,dependency,priority,recency,aging"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"]["preset"], "custom")
+        self.assertEqual(meta["next_up_order"]["order"],
+                         ["milestone", "dependency", "priority", "recency", "aging"])
+
+    def test_order_without_preset_sets_custom(self):
+        """--order alone (no --preset) → preset=custom is implied."""
+        rc, mw, out = _drive(["ph", "--order=aging,priority"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertEqual(meta["next_up_order"]["preset"], "custom")
+
+    def test_clear_on_track_without_key_still_succeeds(self):
+        """--clear on a track that has no next_up_order key still writes ok."""
+        # meta has no next_up_order key
+        t = _t()
+        rc, mw, out = _drive(["ph", "--clear"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_order", meta)
+
+    def test_track_not_found_returns_1(self):
+        """Unrecognized track name → rc=1."""
+        rc, mw, out = _drive(["unknown-track", "--preset=flow"])
+        self.assertEqual(rc, 1)
+        mw.assert_not_called()
+
+    def test_does_not_touch_next_up_issue_list(self):
+        """set-next-up must not modify the next_up issue-list key."""
+        t = _t(meta={"status": "active", "next_up": [101, 102]})
+        rc, mw, out = _drive(["ph", "--preset=flow"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        # next_up issue list must be unchanged
+        self.assertEqual(meta.get("next_up"), [101, 102])
+
+    def test_named_preset_plus_order_warns_and_ignores_order(self):
+        """--preset=<named> + --order: WARN on stderr; named preset wins, order dropped."""
+        base_cfg = {"notes_root": "/tmp"}
+        t = _t()
+        with patch("commands.set_next_up.load_config", return_value=base_cfg), \
+             patch("commands.set_next_up.discover_tracks", return_value=[t]), \
+             patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+             patch("commands.set_next_up.write_file") as mw:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = set_next_up.run(["ph", "--preset=priority-driven",
+                                      "--order=aging,priority"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        # Named preset wins — the co-supplied order is NOT stored.
+        self.assertEqual(meta["next_up_order"], {"preset": "priority-driven"})
+        self.assertIn("WARN", err.getvalue())
+        self.assertIn("--order is ignored", err.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/work-plan/work_plan.py

@@ -60,6 +60,7 @@ SUBCOMMANDS = {
     "auth-status": "commands.auth_status",
     "list-open-issues": "commands.list_open_issues",
     "set": "commands.set_field",
+    "set-next-up": "commands.set_next_up",
     "new-track": "commands.new_track",
     "rename-track": "commands.rename_track",
     "set-notes-root": "commands.set_notes_root",
@@ -166,6 +167,10 @@ DESCRIPTIONS = [
      "Guarded edit of a track's frontmatter fields (status, launch_priority, milestone_alignment, blockers, next_up). Validates field names + status values; blockers/next_up take comma-separated issue numbers. Setting `next_up` here writes ONLY the frontmatter field — for next_up plus a session-log entry (and a body refresh), use `handoff --set-next` instead. Writes into a PUBLIC repo only with a confirm token: without one it prints {needs_confirm, reason, token} and makes no change (the VS Code viewer surfaces that as a modal, then re-invokes with --confirm=<token>).",
      "Programmatic/GUI edits that have no dedicated verb — e.g. the VS Code extension changing a status or blockers list. On the terminal you'll usually use the named verbs instead.",
      "/work-plan set ux-redesign status=parked"),
+    ("set-next-up", "<track | track@repo> (--preset=<name> | --order=a,b,c | --clear) [--repo=<key>] [--confirm=<token>]",
+     "Configure the ranking preset for a track's auto next_up suggestion. --preset sets one of the named presets (flow, priority-driven, backlog) or 'custom' (which requires --order). --order=a,b,c sets a custom comma-separated criterion list (milestone, dependency, priority, recency, aging). --clear reverts to the global or default preset. Writes next_up_order into the track's frontmatter (does NOT touch the next_up issue list). Public-repo gated: without --confirm it prints {needs_confirm, reason, token} and makes no change.",
+     "When you want a track to use a different ranking order than the default (flow). Use priority-driven for pure backlog work with no milestones, backlog to surface oldest stalled issues first.",
+     "/work-plan set-next-up my-track --preset=priority-driven"),
     ("new-track", "<repo> <slug> [--priority=P0..P3] [--milestone=<m>] [--private] [--confirm=<token>]",
      "Create a brand-new track file under notes_root in one headless call. <repo> is either a configured key (e.g. 'myproject') or a bare org/repo slug (e.g. 'your-org/myproject'). Writes frontmatter with status=active and optional priority/milestone. Gates on public repos — prints {needs_confirm, token} and exits cleanly; re-run with --confirm=<token> to proceed.",
      "When a new feature branch or initiative starts and you want the track file created immediately — especially from a non-terminal caller like the VS Code extension that can't interactively run init.",