@stylusnexus/work-plan 2026.6.15-2 → 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.
@@ -280,7 +280,7 @@ A skill has two distinct contracts: (1) the underlying **CLI** that does the wor
 
 | Tool | Install command | Then invoke as |
 |---|---|---|
-| **npm (standalone CLI / any editor)** | `npm install -g @stylusnexus/work-plan` (requires `python3` + `yq` + `gh` already on PATH — the postinstall warns if any are missing). | `work-plan <subcommand>` |
+| **npm (standalone CLI / any editor)** | `npm install -g @stylusnexus/work-plan` (requires `python3` + `yq` + `gh` already on PATH — the CLI warns on first run if any are missing). | `work-plan <subcommand>` |
 | **Claude Code** | **Plugin (recommended):** `/plugin marketplace add stylusnexus/agent-plugins` → `/plugin install work-plan@stylus-nexus`. Or script: `./install.sh` / `.\install.ps1` | Plugin: `/work-plan:brief` … `/work-plan:run <sub>`. Script: bare `/work-plan <subcommand>` |
 | **Codex** | **Plugin:** `codex plugin marketplace add stylusnexus/agent-plugins` → `codex plugin add work-plan@stylus-nexus`. Or script: `./install.sh --target=$HOME/.agents` | Plugin: `@work-plan` / `/skills`. Script: direct CLI |
 | **Cursor** | Skip installer. Clone repo + copy `shims/cursor/work-plan.cursorrules` into your project's `.cursorrules` (or merge it in) | `python3 <toolkit>/skills/work-plan/work_plan.py <sub>` — alias `wp` recommended |

package/VERSION

@@ -1 +1 @@
-2026.06.15+c80ece1
+2026.06.15+488753b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.15-2",
+  "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"
@@ -8,14 +8,10 @@
   "files": [
     "bin/",
     "skills/work-plan/",
-    "scripts/npm-check-deps.js",
     "VERSION",
     "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "postinstall": "node scripts/npm-check-deps.js"
-  },
   "engines": {
     "node": ">=18"
   },

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

@@ -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]
 

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_export_command.py

@@ -290,6 +290,19 @@ class ExportCommandUntrackedTest(unittest.TestCase):
         self.assertEqual(rc, 0)
         self.assertEqual(out["untracked"], [])
 
+    def test_empty_track_still_surfaces_untracked(self):
+        """A repo whose only track has issues:[] must still surface its open
+        issues as untracked (#342). repo_to_numbers omits such a track, so the
+        untracked loop must key off repos-with-tracks, not tracked issues."""
+        tracks = [_track("general", _SHARED_REPO, [])]  # empty track
+        export_map = {}  # no tracked issues to fetch
+        open_rows = {_SHARED_REPO: [_ISSUE_A, _ISSUE_C]}  # but the repo has open issues
+        rc, out = self._run_with_mocks(tracks, export_map, open_rows)
+        self.assertEqual(rc, 0)
+        entry = next(e for e in out["untracked"] if e["repo"] == _SHARED_REPO)
+        nums = sorted(i["number"] for i in entry["issues"])
+        self.assertEqual(nums, [1, 3])  # both open issues are untracked
+
     def test_schema_stays_1_with_untracked(self):
         tracks = [_track("alpha", _SHARED_REPO, [1])]
         open_rows = {_SHARED_REPO: [_ISSUE_A, _ISSUE_B]}

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()

package/scripts/npm-check-deps.js

@@ -1,44 +0,0 @@
-#!/usr/bin/env node
-// Postinstall check for the @stylusnexus/work-plan npm package.
-//
-// The work-plan CLI is pure Python and shells out to three external tools at
-// runtime. npm can't install them (they're not npm packages), so we just check
-// they're on PATH and print a friendly heads-up if any are missing. This NEVER
-// fails the install — a missing tool is the user's to fix, and the CLI prints
-// its own clear error if one is absent when actually run.
-
-const { execSync } = require("node:child_process");
-
-const TOOLS = [
-  { cmd: "python3", why: "runs the CLI", hint: "https://www.python.org/downloads/ (or `brew install python`)" },
-  { cmd: "yq", why: "parses config + frontmatter (mikefarah/yq, the Go one — NOT the python yq)", hint: "brew install yq  ·  https://github.com/mikefarah/yq" },
-  { cmd: "gh", why: "reads GitHub issue state", hint: "brew install gh  ·  https://cli.github.com" },
-];
-
-function have(cmd) {
-  try {
-    const probe = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
-    execSync(probe, { stdio: "ignore", shell: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-try {
-  const missing = TOOLS.filter((t) => !have(t.cmd));
-  if (missing.length) {
-    const lines = [
-      "",
-      "  work-plan installed. It needs a few tools on your PATH that npm can't install:",
-      ...missing.map((t) => `    • ${t.cmd} — ${t.why}\n        ${t.hint}`),
-      "",
-      "  (The CLI will tell you specifically if one is missing when you run it.)",
-      "",
-    ];
-    console.warn(lines.join("\n"));
-  }
-} catch {
-  // Never let the check itself break the install.
-}
-process.exit(0);