@stylusnexus/work-plan 2026.6.15-1 → 2026.6.15-2

package/README.md

@@ -108,7 +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`.
+  - **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`. Toggle auto-derivation itself with `--auto=on|off` (no hand-editing frontmatter required).
 - **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.
@@ -523,7 +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-next-up <track> (--preset=<name> \| --order=a,b,c \| --clear \| --auto=on\|off) [--repo=<key>] [--confirm=<token>]` | Configure the ranking preset and/or auto-derivation flag for a track's next_up list. `--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`. `--auto=on` activates `next_up_auto` so brief/orient/export auto-derive the next-up list live from the ranking preset (ignoring the curated list); `--auto=off` clears it to revert to the curated list. `--auto` can be used standalone or combined with `--preset`/`--order`/`--clear`. Writes `next_up_order` and/or `next_up_auto` 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.15+a627bc9
+2026.06.15+c80ece1

package/package.json

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

@@ -1,10 +1,20 @@
 """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>]
+  work_plan.py set-next-up <track> [--repo=<key>]
+      (--preset=<name> | --order=a,b,c | --clear | --auto=on|off)
+      [--confirm=<token>]
 
-Writes `next_up_order` into the track's frontmatter. Does NOT touch the
-`next_up` issue-list key.
+Writes `next_up_order` and/or `next_up_auto` into the track's frontmatter.
+Does NOT touch the `next_up` issue-list key.
+
+  --preset=<name>   Set one of the named ranking presets (flow, priority-driven,
+                    backlog) or 'custom' (which requires --order).
+  --order=a,b,c     Set a custom comma-separated criterion list.
+  --clear           Remove the next_up_order key (reverts to global/default).
+  --auto=on|off     Toggle the next_up_auto flag. When on, brief/orient/export
+                    auto-derive the next-up list via the ranking preset (#326).
+                    Can be used standalone or combined with --preset/--order/--clear.
 
 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
@@ -22,12 +32,12 @@ from lib.next_up import CRITERIA, PRESETS
 
 def run(args: list[str]) -> int:
     flags, positional = parse_flags(
-        args, {"--confirm", "--repo", "--clear", "--preset", "--order"}
+        args, {"--confirm", "--repo", "--clear", "--preset", "--order", "--auto"}
     )
     if not positional:
         print(
             "usage: work_plan.py set-next-up <track> "
-            "(--preset=<name> | --order=a,b,c | --clear) "
+            "(--preset=<name> | --order=a,b,c | --clear | --auto=on|off) "
             "[--repo=<key>] [--confirm=<token>]"
         )
         return 2
@@ -41,11 +51,27 @@ def run(args: list[str]) -> int:
     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
+    auto_raw = flags.get("--auto") if flags.get("--auto") is not True else None
+
+    # Parse and validate --auto value
+    auto_value = None  # None means not specified
+    if auto_raw is not None:
+        auto_lower = auto_raw.lower() if isinstance(auto_raw, str) else ""
+        if auto_lower == "on":
+            auto_value = True
+        elif auto_lower == "off":
+            auto_value = False
+        else:
+            print(
+                f"ERROR: --auto must be 'on' or 'off', got {auto_raw!r}",
+                file=sys.stderr,
+            )
+            return 2
 
-    # Must have at least one of --preset, --order, or --clear
-    if not clear and preset_flag is None and order_flag is None:
+    # Must have at least one of --preset, --order, --clear, or --auto
+    if not clear and preset_flag is None and order_flag is None and auto_value is None:
         print(
-            "ERROR: specify --preset=<name>, --order=a,b,c, or --clear",
+            "ERROR: specify --preset=<name>, --order=a,b,c, --clear, or --auto=on|off",
             file=sys.stderr,
         )
         return 2
@@ -123,8 +149,19 @@ def run(args: list[str]) -> int:
 
     if clear:
         track.meta.pop("next_up_order", None)
+        if auto_value is not None:
+            _apply_auto(track, auto_value)
         write_file(track.path, track.meta, track.body)
         print(f"✓ cleared next_up_order on {track.name}")
+        if auto_value is not None:
+            _print_auto_result(track, auto_value)
+        return 0
+
+    # If --auto is the only flag (no preset/order/clear), write just the auto flag.
+    if preset_flag is None and order_list is None and auto_value is not None:
+        _apply_auto(track, auto_value)
+        write_file(track.path, track.meta, track.body)
+        _print_auto_result(track, auto_value)
         return 0
 
     # Build the next_up_order mapping
@@ -145,10 +182,29 @@ def run(args: list[str]) -> int:
             )
 
     track.meta["next_up_order"] = nuo
+    if auto_value is not None:
+        _apply_auto(track, auto_value)
     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}")
+    if auto_value is not None:
+        _print_auto_result(track, auto_value)
     return 0
+
+
+def _apply_auto(track: "SimpleNamespace", auto_value: bool) -> None:
+    """Mutate track.meta to set or remove next_up_auto."""
+    if auto_value:
+        track.meta["next_up_auto"] = True
+    else:
+        track.meta.pop("next_up_auto", None)
+
+
+def _print_auto_result(track: "SimpleNamespace", auto_value: bool) -> None:
+    if auto_value:
+        print(f"✓ set next_up_auto=true on {track.name}")
+    else:
+        print(f"✓ cleared next_up_auto on {track.name}")

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

@@ -124,10 +124,8 @@ def build_export(tracks, issues_by_track, visibility, now: str,
                 in_progress_nums=in_progress_set,
                 order=next_up_order,
             )
-            next_up_is_auto = True
         else:
             next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
-            next_up_is_auto = False
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
@@ -155,9 +153,11 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "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,
-            # True when `next_up` above was auto-derived from the ranking preset
-            # (next_up_auto: true), not read from the curated list (#326).
-            "next_up_auto": next_up_is_auto,
+            # True when the track has `next_up_auto: true` set in its frontmatter,
+            # meaning the next-up list is auto-derived from the ranking preset (#326).
+            # Reflects the SETTING, not whether derivation actually ran (so the
+            # viewer toggle shows On even when a track has zero open issues).
+            "next_up_auto": bool(t.meta.get("next_up_auto")),
         })
     out["untracked"] = [
         {"repo": repo, "issues": [normalize_issue(r) for r in rows]}

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

@@ -86,6 +86,31 @@ class BuildExportNextUpAutoTest(unittest.TestCase):
         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."""

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

@@ -197,5 +197,100 @@ class SetNextUpTest(unittest.TestCase):
         self.assertIn("--order is ignored", err.getvalue())
 
 
+class SetNextUpAutoFlagTest(unittest.TestCase):
+    """Tests for --auto=on|off flag on set-next-up."""
+
+    def _drive_with_stderr(self, args, vis="PRIVATE", cfg=None, track=None):
+        """Like _drive but also captures stderr."""
+        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:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = set_next_up.run(args)
+        return rc, mw, out.getvalue(), err.getvalue()
+
+    def test_auto_on_writes_next_up_auto_true(self):
+        """--auto=on sets next_up_auto: True in track meta."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+
+    def test_auto_off_removes_next_up_auto(self):
+        """--auto=off removes next_up_auto from track meta."""
+        t = _t(meta={"status": "active", "next_up_auto": True})
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_auto", meta)
+
+    def test_auto_off_on_track_without_key_still_succeeds(self):
+        """--auto=off on a track with no next_up_auto key still writes ok (no KeyError)."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_auto", meta)
+
+    def test_auto_bogus_returns_rc2_no_write(self):
+        """--auto=bogus → rc=2 and no write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=bogus"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_auto_standalone_private_writes(self):
+        """--auto=on alone (no --preset/--order/--clear) is accepted on private repo."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+
+    def test_auto_standalone_public_needs_confirm(self):
+        """--auto=on alone on a PUBLIC repo → needs_confirm, no write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_auto_standalone_public_with_valid_confirm_writes(self):
+        """--auto=on alone on PUBLIC repo with valid --confirm token proceeds to write."""
+        tok = make_token("o/r", "ph")
+        rc, mw, out, err = self._drive_with_stderr(
+            ["ph", "--auto=on", f"--confirm={tok}"], vis="PUBLIC"
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+
+    def test_auto_on_combined_with_preset_writes_both(self):
+        """--auto=on --preset=backlog sets BOTH next_up_auto AND next_up_order in one write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on", "--preset=backlog"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+        self.assertEqual(meta.get("next_up_order"), {"preset": "backlog"})
+
+    def test_auto_on_prints_success_message(self):
+        """--auto=on prints a clear success line."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertIn("next_up_auto", out)
+        self.assertIn("true", out.lower())
+
+    def test_auto_off_prints_success_message(self):
+        """--auto=off prints a clear success line."""
+        t = _t(meta={"status": "active", "next_up_auto": True})
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"], track=t)
+        self.assertIn("next_up_auto", out)
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/work_plan.py

@@ -167,10 +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"),
+    ("set-next-up", "<track | track@repo> (--preset=<name> | --order=a,b,c | --clear | --auto=on|off) [--repo=<key>] [--confirm=<token>]",
+     "Configure the ranking preset and/or auto-derivation flag for a track's next_up list. --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. --auto=on activates auto-derivation (brief/orient/export derive next-up live via the ranking preset instead of the curated list); --auto=off reverts to the curated list. --auto can be used standalone or combined with --preset/--order/--clear. Writes next_up_order and/or next_up_auto 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), or to activate auto-derivation so the viewer always shows a freshly-ranked list. 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 --auto=on"),
     ("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.",