@stylusnexus/work-plan 2026.6.14 → 2026.6.15-2

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):
@@ -46,6 +49,69 @@ class BuildExportTest(unittest.TestCase):
         self.assertIsNone(out["tracks"][0]["path"])
         json.dumps(out)  # null is serializable
 
+class BuildExportNextUpAutoTest(unittest.TestCase):
+    """next_up_auto: true → export derives next_up live via the ranking preset."""
+
+    def _open(self, n, pri, ms="v1"):
+        return {"number": n, "state": "open", "title": f"#{n}",
+                "labels": [{"name": f"priority/{pri}"}], "milestone": {"title": ms},
+                "updatedAt": "2026-06-10T00:00:00Z", "blocked_by": [], "blocking": []}
+
+    def _track_auto(self, auto):
+        meta = {"status": "active", "launch_priority": "P2", "milestone_alignment": "v1",
+                "blockers": [], "next_up": [7], "depends_on": [],
+                "github": {"repo": "o/r", "issues": [1, 2, 3]}}
+        if auto:
+            meta["next_up_auto"] = True
+        return SimpleNamespace(name="t", repo="o/r", tier="private",
+                               path=Path("/tmp/notes/t.md"), folder="myrepo", meta=meta)
+
+    def _issues(self):
+        # P0 #3, P1 #2, P2 #1 — flow ranks by priority within the same milestone.
+        return [self._open(1, "P2"), self._open(2, "P1"), self._open(3, "P0")]
+
+    def test_auto_derives_and_flags(self):
+        out = build_export([self._track_auto(True)],
+                           {("o/r", "t"): self._issues()},
+                           {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertEqual(tr["next_up"], [3, 2, 1])      # P0 → P1 → P2 (ignores stored [7])
+        self.assertTrue(tr["next_up_auto"])
+
+    def test_no_auto_uses_stored_list(self):
+        out = build_export([self._track_auto(False)],
+                           {("o/r", "t"): self._issues()},
+                           {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertEqual(tr["next_up"], [7])            # the curated list, unchanged
+        self.assertFalse(tr["next_up_auto"])
+
+    def test_auto_on_with_zero_open_issues_still_exports_flag_true(self):
+        """next_up_auto: true + zero fetched issues → next_up_auto=True in export (the
+        SETTING, not whether auto-derivation actually ran).  Viewer toggle must show
+        On even when there are no issues to rank.
+
+        When no issues are fetched, the auto-derivation branch does not run (there's
+        nothing to rank); the export still emits next_up_auto=True so the viewer
+        knows the flag is on.  The next_up list itself falls through to the curated
+        list (which may be non-empty — that's acceptable and a separate concern)."""
+        # Use a track with no stored next_up to isolate the flag assertion cleanly.
+        meta = {"status": "active", "launch_priority": "P2", "milestone_alignment": "v1",
+                "blockers": [], "next_up": [], "depends_on": [],
+                "next_up_auto": True,
+                "github": {"repo": "o/r", "issues": []}}
+        from types import SimpleNamespace
+        from pathlib import Path
+        t = SimpleNamespace(name="t", repo="o/r", tier="private",
+                            path=Path("/tmp/notes/t.md"), folder="myrepo", meta=meta)
+        out = build_export([t],
+                           {("o/r", "t"): []},           # zero issues fetched
+                           {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertTrue(tr["next_up_auto"])              # flag reflects setting, not derivation
+        self.assertEqual(tr["next_up"], [])              # no issues → empty list
+
+
 class BuildExportNextUpFilterTest(unittest.TestCase):
     """next_up entries whose issue is closed in the fetched payload are filtered out."""
 
@@ -459,6 +525,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_git_state.py

@@ -1,6 +1,7 @@
 """Tests for git_state pure functions."""
 import unittest
 import sys
+from datetime import datetime, timedelta
 from pathlib import Path
 from unittest import mock
 
@@ -49,40 +50,74 @@ class BranchInProgressTest(unittest.TestCase):
 
 
 class HotIssueNumbersTest(unittest.TestCase):
+    def setUp(self):
+        # hot_issue_numbers memoizes per resolved path; reset between cases so a
+        # prior test's "/repo" result doesn't leak into the next.
+        from lib import git_state
+        git_state._reset_hot_cache()
+
+    def _ref_line(self, branch, age_hours):
+        ts = int((datetime.now() - timedelta(hours=age_hours)).timestamp())
+        return f"{branch}\t{ts}"
+
+    def _enum(self, *lines):
+        return mock.Mock(return_value=mock.Mock(returncode=0,
+                                                stdout="\n".join(lines) + "\n"))
+
     def test_returns_empty_when_repo_missing(self):
         self.assertEqual(hot_issue_numbers(None), set())
         self.assertEqual(hot_issue_numbers(Path("/nonexistent")), set())
 
-    def test_maps_hot_feat_and_fix_branches_to_numbers(self):
-        listing = "dev\nmain\nfeat/271-foo\nfix/88-bar\nchore/x\nwork-plan/plan\n"
-        enum = mock.Mock(return_value=mock.Mock(returncode=0, stdout=listing))
+    def test_recent_feat_and_fix_branches_are_hot(self):
+        # Two recently-committed feat/fix branches + cold/non-matching ones.
+        lines = ["dev\t0", "main\t0",
+                 self._ref_line("feat/271-foo", 1),    # 1h ago -> hot
+                 self._ref_line("fix/88-bar", 5),       # 5h ago -> hot
+                 self._ref_line("feat/9-old", 100),     # 100h ago -> cold
+                 "chore/x\t0", "work-plan/plan\t0"]
         with mock.patch("lib.git_state.Path.exists", return_value=True), \
-             mock.patch("lib.git_state._git", enum), \
-             mock.patch("lib.git_state.branch_in_progress",
-                        side_effect=lambda b, p: b in ("feat/271-foo", "fix/88-bar")):
+             mock.patch("lib.git_state._git", self._enum(*lines)), \
+             mock.patch("lib.git_state.current_branch", return_value=None):
             self.assertEqual(hot_issue_numbers(Path("/repo")), {271, 88})
 
     def test_no_substring_collision_2710_is_not_271(self):
-        listing = "feat/2710-y\n"
         with mock.patch("lib.git_state.Path.exists", return_value=True), \
              mock.patch("lib.git_state._git",
-                        return_value=mock.Mock(returncode=0, stdout=listing)), \
-             mock.patch("lib.git_state.branch_in_progress", return_value=True):
+                        self._enum(self._ref_line("feat/2710-y", 1))), \
+             mock.patch("lib.git_state.current_branch", return_value=None):
             self.assertEqual(hot_issue_numbers(Path("/repo")), {2710})
 
     def test_cold_matched_branch_excluded(self):
-        listing = "feat/271-foo\n"
         with mock.patch("lib.git_state.Path.exists", return_value=True), \
              mock.patch("lib.git_state._git",
-                        return_value=mock.Mock(returncode=0, stdout=listing)), \
-             mock.patch("lib.git_state.branch_in_progress", return_value=False):
+                        self._enum(self._ref_line("feat/271-foo", 48))), \
+             mock.patch("lib.git_state.current_branch", return_value=None):
             self.assertEqual(hot_issue_numbers(Path("/repo")), set())
 
+    def test_uncommitted_on_current_branch_is_hot_even_if_cold(self):
+        # A cold (old-tip) feat branch that's checked out with uncommitted work.
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git",
+                        self._enum(self._ref_line("feat/271-foo", 200))), \
+             mock.patch("lib.git_state.current_branch", return_value="feat/271-foo"), \
+             mock.patch("lib.git_state.has_uncommitted", return_value=True):
+            self.assertEqual(hot_issue_numbers(Path("/repo")), {271})
+
     def test_enumeration_failure_returns_empty(self):
         with mock.patch("lib.git_state.Path.exists", return_value=True), \
              mock.patch("lib.git_state._git", return_value=None):
             self.assertEqual(hot_issue_numbers(Path("/repo")), set())
 
+    def test_memoizes_per_resolved_path(self):
+        # Second call with the same path must NOT re-invoke git.
+        enum = self._enum(self._ref_line("feat/271-foo", 1))
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", enum), \
+             mock.patch("lib.git_state.current_branch", return_value=None):
+            self.assertEqual(hot_issue_numbers(Path("/repo")), {271})
+            self.assertEqual(hot_issue_numbers(Path("/repo")), {271})
+            self.assertEqual(enum.call_count, 1)
+
 
 if __name__ == "__main__":
     unittest.main()