@stylusnexus/work-plan 2026.6.15-3 → 2026.6.15-4

package/README.md

@@ -104,7 +104,7 @@ flowchart TB
 
 - **Morning** → `brief` shows multi-track plate, then `orient <track>` produces a ~15-line paste-block to drop into a fresh agent session.
 - **End of work block** → `handoff <track>` captures what you touched. Three ways to set `next_up` for tomorrow:
-  - `handoff <track> --auto-next` — algorithmic (no LLM): top-3 by priority then most-recently-updated, blockers excluded. Interactive `[Y/n/edit]` prompt — accept, edit, or skip.
+  - `handoff <track> --auto-next` — algorithmic (no LLM): top-3 by priority then most-recently-updated, blockers excluded. Interactive `[Y/n/edit]` prompt — accept, edit, or skip. (`--suggest-next` is the read-only, non-interactive sibling: it prints the same suggestion as JSON and writes nothing — the feed the VS Code **Suggest Next-Up (auto)** picker confirms, since the TTY prompt can't run under the extension.)
   - `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.

package/VERSION

@@ -1 +1 @@
-2026.06.15+e3f3cdf
+2026.06.15+488753b

package/package.json

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

@@ -0,0 +1,130 @@
+"""Tests for `handoff --suggest-next` — the read-only JSON suggestion mode (#274).
+
+The VS Code native auto-next picker needs the algorithmic next_up suggestion
+WITHOUT a write or a TTY prompt (the CLI's prompt helpers no-op under VS Code's
+non-TTY stdin). `--suggest-next` computes the same sibling-filtered suggestion as
+`--auto-next` and prints it as JSON; the extension renders + confirms it and
+writes back via `--set-next`. These tests assert: valid JSON shape, sibling-claim
+skips surface in `skipped` (not written), no frontmatter is mutated, and the
+soft-error payloads (no repo / no issues) stay parseable with exit 0.
+"""
+import io
+import json
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import handoff
+from lib.frontmatter import parse_file, write_file
+
+
+def _make_track(dir_path: Path, slug: str, *, repo: str, status: str = "active",
+                next_up=None, issues=None) -> Path:
+    meta = {
+        "track": slug,
+        "status": status,
+        "launch_priority": "P1",
+        "github": {"repo": repo,
+                   "issues": list([100, 200] if issues is None else issues),
+                   "branches": []},
+        "next_up": list(next_up or []),
+    }
+    path = dir_path / f"{slug}.md"
+    write_file(path, meta, f"\n# {slug}\n\nBody.\n")
+    return path
+
+
+def _open_issue(num: int, *, priority: str = "P1", milestone=None) -> dict:
+    return {
+        "number": num,
+        "title": f"issue-{num}",
+        "state": "OPEN",
+        "labels": [{"name": f"priority/{priority}"}],
+        "updatedAt": "2026-04-30T00:00:00Z",
+        "milestone": milestone,
+    }
+
+
+class SuggestNextJsonTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.notes_root = Path(self.tmp.name) / "notes_root"
+        self.repo_dir = self.notes_root / "demo"
+        self.repo_dir.mkdir(parents=True)
+        self.cfg = {
+            "notes_root": str(self.notes_root),
+            "repos": {"demo": {"github": "stylusnexus/Demo"}},
+        }
+        self._patches = [
+            mock.patch("commands.handoff.load_config", return_value=self.cfg),
+            mock.patch("commands.handoff.has_uncommitted", return_value=False),
+        ]
+        for p in self._patches:
+            p.start()
+
+    def tearDown(self):
+        for p in self._patches:
+            p.stop()
+        self.tmp.cleanup()
+
+    def _run(self, track_name, *, issues_response):
+        buf = io.StringIO()
+        with mock.patch("commands.handoff.fetch_issues", return_value=issues_response), \
+             redirect_stdout(buf):
+            rc = handoff.run([track_name, "--suggest-next"])
+        return rc, buf.getvalue()
+
+    def test_emits_valid_json_with_decorated_suggestions(self):
+        target = _make_track(self.repo_dir, "track-a", repo="stylusnexus/Demo",
+                             issues=[100, 200])
+        rc, out = self._run("track-a",
+                            issues_response=[_open_issue(100, milestone={"title": "v1.0.0"}),
+                                             _open_issue(200)])
+        self.assertEqual(rc, 0)
+        payload = json.loads(out)
+        self.assertEqual(payload["track"], "track-a")
+        self.assertEqual(payload["repo"], "stylusnexus/Demo")
+        nums = [s["number"] for s in payload["suggested"]]
+        self.assertEqual(sorted(nums), [100, 200])
+        first = next(s for s in payload["suggested"] if s["number"] == 100)
+        self.assertEqual(first["title"], "issue-100")
+        self.assertEqual(first["priority"], "P1")
+        self.assertEqual(first["milestone"], "v1.0.0")
+
+    def test_read_only_does_not_write_next_up(self):
+        target = _make_track(self.repo_dir, "track-a", repo="stylusnexus/Demo",
+                             issues=[100, 200], next_up=[7])
+        rc, out = self._run("track-a",
+                            issues_response=[_open_issue(100), _open_issue(200)])
+        self.assertEqual(rc, 0)
+        meta, _ = parse_file(target)
+        self.assertEqual(meta["next_up"], [7])  # untouched by a read-only suggest
+
+    def test_sibling_claimed_issue_lands_in_skipped_not_suggested(self):
+        _make_track(self.repo_dir, "track-a", repo="stylusnexus/Demo", issues=[100, 200])
+        _make_track(self.repo_dir, "track-b", repo="stylusnexus/Demo", next_up=[100])
+        rc, out = self._run("track-a",
+                            issues_response=[_open_issue(100), _open_issue(200)])
+        payload = json.loads(out)
+        self.assertEqual([s["number"] for s in payload["suggested"]], [200])
+        self.assertEqual(payload["skipped"], [{"number": 100, "claimed_by": "track-b"}])
+
+    def test_no_issues_attached_is_soft_error_with_empty_suggested(self):
+        _make_track(self.repo_dir, "track-a", repo="stylusnexus/Demo", issues=[])
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = handoff.run(["track-a", "--suggest-next"])
+        self.assertEqual(rc, 0)
+        payload = json.loads(buf.getvalue())
+        self.assertEqual(payload["suggested"], [])
+        self.assertIn("error", payload)
+
+
+if __name__ == "__main__":
+    unittest.main()