@stylusnexus/work-plan 2026.6.15 → 2026.6.18

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

@@ -1,8 +1,10 @@
 """brief subcommand — fully featured."""
+import os
 from datetime import datetime
 from pathlib import Path
 
 from lib.config import load_config, ConfigError
+from lib.cwd_repo import resolve_repo_for_dir
 from lib.tracks import (
     discover_tracks, discover_archived_tracks, filter_tracks_by_repo,
     priority_rank, recency_sort_key,
@@ -24,9 +26,9 @@ from lib.render import time_aware_framing, render_track_row, render_archived_reo
 
 def run(args: list[str]) -> int:
     flags, _ = parse_flags(args, {"--repo"})
-    repo_key = flags.get("--repo")
-    if repo_key is True:
-        print("usage: work_plan.py brief [--repo=<key>]")
+    repo_arg = flags.get("--repo")
+    if repo_arg is True:
+        print("usage: work_plan.py brief [--repo=<key> | --repo=all]")
         return 2
 
     try:
@@ -36,15 +38,39 @@ def run(args: list[str]) -> int:
         return 1
 
     tracks = discover_tracks(cfg)
+
+    # Resolve the effective scope key ONCE, then thread it through both the track
+    # filter and the archived-reopen pass so the two can never diverge (#358):
+    #   explicit --repo=<key> → scope to it (unchanged behavior, no banner)
+    #   explicit --repo=all   → force the full view (no scope, no auto-detect)
+    #   --repo omitted        → auto-detect from cwd (unless opted out); banner on hit
+    auto_scoped = False
+    if isinstance(repo_arg, str):
+        repo_key = None if repo_arg.lower() == "all" else repo_arg
+    else:
+        repo_key = None
+        if cfg.get("brief_auto_scope", True):
+            match = resolve_repo_for_dir(cfg, os.getcwd())
+            # Only auto-scope when the detected repo actually has tracks — a
+            # convenience must never hide tracks you'd otherwise see.
+            if match and filter_tracks_by_repo(tracks, match["key"]):
+                repo_key = match["key"]
+                auto_scoped = True
+
     if repo_key:
         scoped = filter_tracks_by_repo(tracks, repo_key)
         if not scoped:
+            # Reachable only via an explicit --repo (the auto path above already
+            # guaranteed a non-empty match).
             print(f"No tracks found for repo '{repo_key}'.")
             available = sorted((cfg.get("repos") or {}).keys())
             if available:
                 print(f"Configured repo keys: {', '.join(available)}")
             return 0
         tracks = scoped
+        if auto_scoped:
+            print(f"Scoped to repo '{repo_key}' (cwd). Use --repo=all to see everything.")
+            print()
     active = [t for t in tracks if t.has_frontmatter
               and t.meta.get("status") in ("active", "in-progress", "blocked")]
 

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

@@ -0,0 +1,104 @@
+"""dedupe-tiers — remove private track copies shadowed by a shared twin (#359).
+
+When a track is promoted to the shared tier (a repo's `.work-plan/`), the private
+original under `notes_root` is normally moved out by `push-track`. But bulk or
+manual promotion — or a failed unlink mid-promote — leaves the private copy
+behind. `discover_tracks` then resolves the collision ("using shared") but warns
+on EVERY invocation, with no built-in way to clean up.
+
+This verb removes the orphaned private copies that their shared twin supersedes,
+and REFUSES to touch any whose private copy still references issue numbers the
+shared one lacks — so no tracked work is ever silently dropped. The no-data-loss
+invariant is `issue_refs(private) ⊆ issue_refs(shared)`.
+
+Default is a dry-run report. Pass `--apply` to delete the safe orphans; the
+deletion lands in notes_root and the dispatcher's auto-commit makes it undoable.
+
+Usage:
+    work_plan.py dedupe-tiers [--repo=<key>] [--apply]
+"""
+import sys
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import find_tier_duplicates, issue_refs
+from lib.prompts import parse_flags
+
+KNOWN = {"--repo", "--apply"}
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, KNOWN)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py dedupe-tiers [--repo=<key>] [--apply]",
+              file=sys.stderr)
+        return 2
+    apply = bool(flags.get("--apply"))
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    pairs = find_tier_duplicates(cfg)
+    if repo_key:
+        k = repo_key.lower()
+        pairs = [(s, p) for (s, p) in pairs
+                 if (s.folder and s.folder.lower() == k)
+                 or (s.repo and s.repo.lower() == k)]
+
+    if not pairs:
+        scope = f" for repo '{repo_key}'" if repo_key else ""
+        print(f"No shared/private duplicate tracks found{scope}. Nothing to dedupe.")
+        return 0
+
+    safe: list = []      # (shared, private) — private issue refs ⊆ shared
+    diverged: list = []  # (shared, private, extra_refs) — private has unique refs
+    for s, p in pairs:
+        extra = issue_refs(p) - issue_refs(s)
+        if extra:
+            diverged.append((s, p, extra))
+        else:
+            safe.append((s, p))
+
+    print(f"Found {len(pairs)} shared/private duplicate track(s):")
+    print(f"  {len(safe)} safe to remove (private issue refs ⊆ shared)")
+    print(f"  {len(diverged)} diverged — kept for manual review")
+    print()
+
+    for s, p in safe:
+        print(f"  ✓ {p.name}  (repo {s.repo or s.folder}) — private superseded by shared")
+        print(f"      private: {p.path}")
+    for s, p, extra in diverged:
+        refs = ", ".join(f"#{n}" for n in sorted(extra))
+        print(f"  ⚠ {p.name}  (repo {s.repo or s.folder}) — private has issue refs "
+              f"not in shared: {refs}")
+        print(f"      KEPT: {p.path} — reconcile by hand")
+
+    if not apply:
+        print()
+        if safe:
+            print(f"Dry run. Re-run with --apply to remove {len(safe)} private orphan(s).")
+        else:
+            print("Dry run. Nothing safe to remove automatically.")
+        return 0
+
+    if not safe:
+        print()
+        print("Nothing removed — every duplicate diverged and needs manual review.")
+        return 0
+
+    removed = 0
+    for s, p in safe:
+        try:
+            Path(p.path).unlink()
+            removed += 1
+        except OSError as e:
+            print(f"WARN: could not remove {p.path}: {e}", file=sys.stderr)
+
+    print()
+    print(f"Removed {removed} private orphan(s). "
+          f"{len(diverged)} diverged track(s) left for manual review.")
+    return 0

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

@@ -2,7 +2,7 @@
 import json
 from datetime import datetime, date
 from lib.config import load_config, ConfigError, resolve_local_path_for_folder
-from lib.tracks import discover_tracks
+from lib.tracks import discover_tracks, find_tier_duplicates, issue_refs
 from lib.github_state import fetch_export_issues, fetch_open_issues, repo_visibility
 from lib.git_state import hot_issue_numbers
 from lib.export_model import build_export
@@ -93,11 +93,19 @@ def run(args: list[str]) -> int:
             visibility[t.repo] = repo_visibility(t.repo)
 
     # Compute untracked: open issues not referenced by any track, per repo.
+    # Iterate over every repo that has ANY track — NOT just repos in
+    # repo_to_numbers (which only collects tracks whose github.issues is
+    # non-empty). A repo whose only track has `issues: []` must still get its
+    # open issues surfaced as untracked; otherwise creating an empty track in a
+    # previously-trackless repo makes its open issues vanish — neither in the
+    # (empty) track nor in untracked, and the viewer's trackless fallback
+    # (treeModel.mergeFetchedUntracked) shuts off the moment a track exists (#342).
     # One `gh issue list` call per repo — bounded by the number of tracked repos
     # (typically a handful), not by issue count, so a serial loop is fine.
+    tracked_repos = {t.repo for t in tracks if t.repo}
     untracked_by_repo: dict[str, list] = {}
-    for repo in repo_to_numbers:
-        tracked = set(repo_to_numbers[repo])
+    for repo in tracked_repos:
+        tracked = set(repo_to_numbers.get(repo, []))
         open_rows = fetch_open_issues(repo)
         untracked_by_repo[repo] = [r for r in open_rows if r.get("number") not in tracked]
 
@@ -140,6 +148,22 @@ def run(args: list[str]) -> int:
             if nums:
                 hot_by_track[(t.repo, t.name)] = nums
 
+    # Shared/private tier duplicates (#361): the viewer is otherwise blind to
+    # them — discover_tracks drops the private copy with a stderr-only WARN. We
+    # surface them as a read-only health signal; `safe` mirrors dedupe-tiers'
+    # no-data-loss invariant (private issue refs ⊆ shared), so the viewer can
+    # tell auto-removable orphans from diverged ones needing manual review.
+    tier_duplicates = []
+    for shared_t, private_t in find_tier_duplicates(cfg):
+        tier_duplicates.append({
+            "repo": shared_t.repo,
+            "folder": shared_t.folder,
+            "name": shared_t.name,
+            "shared_path": str(shared_t.path),
+            "private_path": str(private_t.path),
+            "safe": issue_refs(private_t) <= issue_refs(shared_t),
+        })
+
     next_up_default = cfg.get("next_up_default")
     now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
     print(json.dumps(
@@ -148,7 +172,8 @@ def run(args: list[str]) -> int:
                      config_repos=config_repos,
                      plan_by_track=plan_by_track,
                      hot_by_track=hot_by_track,
-                     next_up_default=next_up_default),
+                     next_up_default=next_up_default,
+                     tier_duplicates=tier_duplicates),
         indent=2,
     ))
     return 0

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

@@ -9,6 +9,7 @@ Use --interactive (or -i) for the legacy blank-prompt mode where you fill in
 each section by hand.
 """
 import fnmatch
+import json
 import subprocess
 from datetime import datetime, timedelta
 
@@ -30,9 +31,10 @@ from lib.prompts import prompt_lines, parse_flags, prompt_input
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next", "--repo"})
+    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next", "--suggest-next", "--repo"})
     interactive = flags.get("--interactive", False) or flags.get("-i", False)
     auto_next = flags.get("--auto-next", False)
+    suggest_next = flags.get("--suggest-next", False)
 
     # Support both --set-next=4167,4148 (parse_flags handles via key=value) and
     # --set-next 4167,4148 (space-separated). For the space form, parse_flags
@@ -80,6 +82,12 @@ def run(args: list[str]) -> int:
     if not track:
         return 1
 
+    # --suggest-next: read-only. Compute the algorithmic next_up suggestion and
+    # emit it as JSON for a non-CLI caller (the VS Code native picker, #274) to
+    # render + confirm. No prompt, no write — the caller writes via --set-next.
+    if suggest_next:
+        return _suggest_next_json(track, cfg)
+
     # Apply --set-next first if present, so derived/interactive output reflects it.
     if isinstance(set_next_raw, str):
         rc = _apply_set_next(track, set_next_raw, cfg)
@@ -129,6 +137,81 @@ def _apply_set_next(track, raw: str, cfg: dict) -> int:
     return 0
 
 
+def _compute_auto_next(track, cfg: dict):
+    """Compute the sibling-filtered next_up suggestion (read-only — no prompt,
+    no write). Shared by the interactive --auto-next flow and the --suggest-next
+    JSON output (#274).
+
+    Returns (suggestion, by_num, skipped, had_raw):
+      - suggestion: list[int] — ordered issue numbers to queue
+      - by_num: {int: issue} — fetched issues keyed by number (for decoration)
+      - skipped: list[(int, str)] — (issue, sibling_track) dropped as already-claimed
+      - had_raw: bool — whether the algorithm produced ANY candidate before the
+        sibling filter (distinguishes "no open non-blocker issues" from
+        "all candidates claimed by siblings"). Caller guarantees track.repo and a
+        non-empty issue list.
+    """
+    issue_nums = track.meta.get("github", {}).get("issues") or []
+    issues = fetch_issues(track.repo, issue_nums)
+    blocker_nums = track.meta.get("blockers") or []
+    track_milestone = track.meta.get("milestone_alignment") or None
+    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,
+    )
+    claimed = _sibling_claimed_next_up_map(track, cfg)
+    suggestion, skipped = [], []
+    for num in raw_suggestion:
+        if num in claimed:
+            skipped.append((num, claimed[num]))
+        else:
+            suggestion.append(num)
+    by_num = {i["number"]: i for i in issues}
+    return suggestion, by_num, skipped, bool(raw_suggestion)
+
+
+def _suggest_next_json(track, cfg: dict) -> int:
+    """Emit the algorithmic next_up suggestion as JSON for a non-CLI caller (#274).
+
+    Read-only: never prompts or writes. Soft errors (no repo / no issues) are
+    reported in the payload with an empty `suggested`, so the caller always gets
+    parseable JSON and exit 0; hard errors (track resolution) are handled upstream
+    in run() before this is reached.
+    """
+    out = {
+        "track": track.name,
+        "repo": track.repo,
+        "current": track.meta.get("next_up") or [],
+        "suggested": [],
+        "skipped": [],
+    }
+    if not track.repo:
+        out["error"] = f"track '{track.name}' has no github.repo"
+        print(json.dumps(out))
+        return 0
+    if not (track.meta.get("github", {}).get("issues") or []):
+        out["error"] = f"no issues attached to '{track.name}'"
+        print(json.dumps(out))
+        return 0
+    suggestion, by_num, skipped, _ = _compute_auto_next(track, cfg)
+    for num in suggestion:
+        i = by_num.get(num, {})
+        out["suggested"].append({
+            "number": num,
+            "title": i.get("title", ""),
+            "priority": extract_priority(i.get("labels", [])),
+            "milestone": short_milestone(i.get("milestone")) or "",
+        })
+    out["skipped"] = [{"number": n, "claimed_by": s} for n, s in skipped]
+    print(json.dumps(out))
+    return 0
+
+
 def _apply_auto_next(track, cfg: dict) -> int:
     """Suggest a next_up list from open issues; prompt user to apply/edit/skip.
 
@@ -150,38 +233,19 @@ def _apply_auto_next(track, cfg: dict) -> int:
         print(f"No issues attached to {track.name}; nothing to suggest.")
         return 0
 
-    issues = fetch_issues(track.repo, issue_nums)
-    blocker_nums = track.meta.get("blockers") or []
-    track_milestone = track.meta.get("milestone_alignment") or None
-    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:
+    suggestion, by_num, skipped, had_raw = _compute_auto_next(track, cfg)
+    # Print one line per sibling-claimed skip so the user knows what was dropped.
+    for num, sib in skipped:
+        print(f"↷ skipped #{num} (already next_up on '{sib}')")
+
+    if not had_raw:
         print(f"No open, non-blocker issues for {track.name}; next_up unchanged.")
         return 0
-
-    # Filter sibling-claimed issues out of the suggestion. Print one line
-    # per skip so the user knows what was dropped and why.
-    claimed = _sibling_claimed_next_up_map(track, cfg)
-    suggestion = []
-    for num in raw_suggestion:
-        if num in claimed:
-            print(f"↷ skipped #{num} (already next_up on '{claimed[num]}')")
-        else:
-            suggestion.append(num)
-
     if not suggestion:
         print(f"All suggested issues are already next_up on sibling tracks; next_up unchanged.")
         return 0
 
     # Decorate with title + priority + milestone for the preview.
-    by_num = {i["number"]: i for i in issues}
     print(f"\nSuggested next_up for {track.name}:")
     for num in suggestion:
         i = by_num.get(num, {})

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

@@ -3,11 +3,15 @@
 Runs in sequence:
   1. refresh-md --all --yes  (drift in body status tables)
   2. reconcile --all          (sync track/<slug> labels ↔ frontmatter)
-  3. duplicates               (find consolidation candidates)
+  3. dedupe-tiers             (report shared/private duplicate tracks)
+  4. duplicates               (find consolidation candidates)
 
 One command for the standard weekly maintenance pass.
 
-Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 3 (duplicates)
+Step 3 (dedupe-tiers) is report-only here — it never deletes during hygiene.
+Run `/work-plan dedupe-tiers --apply` directly to remove the safe orphans.
+
+Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 4 (duplicates)
 is per-repo, so:
   - when --repo is set, it's scoped to that repo;
   - when --repo is absent and config has exactly one repo, it runs against
@@ -18,7 +22,7 @@ is per-repo, so:
 Pass --timeout=N to set the gh subprocess timeout for the duplicates step
 (default 30s).
 """
-from commands import refresh_md, reconcile, duplicates
+from commands import refresh_md, reconcile, duplicates, dedupe_tiers
 from lib.config import load_config, ConfigError
 from lib.prompts import parse_flags
 import time
@@ -62,7 +66,7 @@ def run(args: list[str]) -> int:
 
     t0 = time.time()
     print("=" * 60)
-    print(f"WEEKLY HYGIENE — step 1 of 3: refresh-md{scope_label}")
+    print(f"WEEKLY HYGIENE — step 1 of 4: refresh-md{scope_label}")
     print("=" * 60)
     refresh_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
     if yes:
@@ -70,12 +74,12 @@ def run(args: list[str]) -> int:
     rc = refresh_md.run(refresh_args)
     if rc != 0:
         print(f"\n⚠ refresh-md exited with code {rc}; continuing.")
-    print(f"  (step 1/3 done in {time.time() - t0:.1f}s)")
+    print(f"  (step 1/4 done in {time.time() - t0:.1f}s)")
 
     t1 = time.time()
     print()
     print("=" * 60)
-    print(f"WEEKLY HYGIENE — step 2 of 3: reconcile{scope_label}")
+    print(f"WEEKLY HYGIENE — step 2 of 4: reconcile{scope_label}")
     print("=" * 60)
     reconcile_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
     if yes:
@@ -83,7 +87,18 @@ def run(args: list[str]) -> int:
     rc = reconcile.run(reconcile_args)
     if rc != 0:
         print(f"\n⚠ reconcile exited with code {rc}; continuing.")
-    print(f"  (step 2/3 done in {time.time() - t1:.1f}s)")
+    print(f"  (step 2/4 done in {time.time() - t1:.1f}s)")
+
+    t_dt = time.time()
+    print()
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 3 of 4: dedupe-tiers{scope_label} (report-only)")
+    print("=" * 60)
+    dedupe_args = [f"--repo={repo_key}"] if repo_key else []
+    rc = dedupe_tiers.run(dedupe_args)
+    if rc != 0:
+        print(f"\n⚠ dedupe-tiers exited with code {rc}; continuing.")
+    print(f"  (step 3/4 done in {time.time() - t_dt:.1f}s)")
 
     if skip_dups:
         print()
@@ -93,7 +108,7 @@ def run(args: list[str]) -> int:
     t2 = time.time()
     print()
     print("=" * 60)
-    print("WEEKLY HYGIENE — step 3 of 3: duplicates")
+    print("WEEKLY HYGIENE — step 4 of 4: duplicates")
     print("=" * 60)
 
     try:
@@ -122,7 +137,7 @@ def run(args: list[str]) -> int:
     rc = duplicates.run(dupes_args)
     if rc != 0:
         print(f"\n⚠ duplicates exited with code {rc}.")
-    print(f"  (step 3/3 done in {time.time() - t2:.1f}s)")
+    print(f"  (step 4/4 done in {time.time() - t2:.1f}s)")
 
     print()
     print(f"✓ Weekly hygiene complete ({time.time() - t0:.1f}s total). Review the duplicate candidates above and "

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}")