@stylusnexus/work-plan 2026.6.15 → 2026.6.16

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

@@ -0,0 +1,164 @@
+"""cwd → configured-repo resolution (#358/#357 Phase 1).
+
+All git calls are mocked, so these run offline. The resolver shells `git` via
+`lib.git_state._git`, imported into `lib.cwd_repo`'s namespace — so we patch
+`lib.cwd_repo._git`.
+"""
+import sys
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib import cwd_repo
+from lib.cwd_repo import resolve_repo_for_dir, _normalize_remote_url
+
+
+def _proc(stdout="", returncode=0):
+    """A stand-in for subprocess.CompletedProcess as `_git` returns it."""
+    return types.SimpleNamespace(stdout=stdout, returncode=returncode)
+
+
+def _fake_git(toplevel=None, origin=None):
+    """Build a `_git` replacement keyed on the git subcommand.
+
+    `toplevel` / `origin` are raw stdout strings (or None → non-zero exit, i.e.
+    git failed / not a repo / no remote).
+    """
+    def _g(repo_path, *args, **kwargs):
+        if args[:2] == ("rev-parse", "--show-toplevel"):
+            return _proc(toplevel, 0) if toplevel is not None else _proc("", 128)
+        if args[:2] == ("remote", "get-url"):
+            return _proc(origin, 0) if origin is not None else _proc("", 2)
+        return _proc("", 0)
+    return _g
+
+
+# Absolute, non-symlinked paths so .resolve() is a no-op-equal on both sides.
+CFG = {
+    "repos": {
+        "work-plan-toolkit": {
+            "local": "/code/work-plan-toolkit",
+            "github": "stylusnexus/work-plan-toolkit",
+        },
+        "defect-scan": {
+            "local": "/code/defect-scan",
+            "github": "stylusnexus/defect-scan",
+        },
+        # A repo with no local clone — only a remote can match it.
+        "remote-only": {
+            "local": None,
+            "github": "stylusnexus/remote-only",
+        },
+    }
+}
+
+
+class NormalizeRemoteUrlTest(unittest.TestCase):
+    def test_scp_form(self):
+        self.assertEqual(
+            _normalize_remote_url("git@github.com:Org/Repo.git"), "org/repo")
+
+    def test_https_with_git_suffix(self):
+        self.assertEqual(
+            _normalize_remote_url("https://github.com/org/repo.git"), "org/repo")
+
+    def test_https_without_suffix(self):
+        self.assertEqual(
+            _normalize_remote_url("https://github.com/org/repo"), "org/repo")
+
+    def test_ssh_url_form(self):
+        self.assertEqual(
+            _normalize_remote_url("ssh://git@github.com/org/repo.git"), "org/repo")
+
+    def test_all_forms_land_on_same_slug(self):
+        forms = [
+            "git@github.com:org/repo.git",
+            "https://github.com/org/repo.git",
+            "https://github.com/org/repo",
+            "ssh://git@github.com/org/repo.git",
+        ]
+        slugs = {_normalize_remote_url(f) for f in forms}
+        self.assertEqual(slugs, {"org/repo"})
+
+    def test_garbage_returns_none(self):
+        self.assertIsNone(_normalize_remote_url(""))
+        self.assertIsNone(_normalize_remote_url("not-a-url"))
+
+
+class ResolveRepoForDirTest(unittest.TestCase):
+    def test_local_match_at_clone_root(self):
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/work-plan-toolkit")):
+            got = resolve_repo_for_dir(CFG, "/code/work-plan-toolkit")
+        self.assertEqual(got, {
+            "key": "work-plan-toolkit",
+            "github": "stylusnexus/work-plan-toolkit",
+            "matched_by": "local",
+        })
+
+    def test_local_match_from_nested_subdir(self):
+        # cwd is deep inside the clone; toplevel still resolves to the root.
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/work-plan-toolkit")):
+            got = resolve_repo_for_dir(
+                CFG, "/code/work-plan-toolkit/skills/work-plan/lib")
+        self.assertIsNotNone(got)
+        self.assertEqual(got["key"], "work-plan-toolkit")
+        self.assertEqual(got["matched_by"], "local")
+
+    def test_remote_match_when_local_is_null(self):
+        # Not a configured local path, but origin matches the remote-only repo.
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/somewhere/else",
+                                         origin="git@github.com:stylusnexus/remote-only.git")):
+            got = resolve_repo_for_dir(CFG, "/somewhere/else")
+        self.assertEqual(got, {
+            "key": "remote-only",
+            "github": "stylusnexus/remote-only",
+            "matched_by": "remote",
+        })
+
+    def test_local_wins_over_remote_when_they_disagree(self):
+        # toplevel == defect-scan's clone, but origin points at work-plan-toolkit.
+        # The local-path key must win.
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/defect-scan",
+                                         origin="git@github.com:stylusnexus/work-plan-toolkit.git")):
+            got = resolve_repo_for_dir(CFG, "/code/defect-scan")
+        self.assertEqual(got["key"], "defect-scan")
+        self.assertEqual(got["matched_by"], "local")
+
+    def test_no_match_inside_unconfigured_repo(self):
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/unknown",
+                                         origin="git@github.com:someone/unknown.git")):
+            self.assertIsNone(resolve_repo_for_dir(CFG, "/code/unknown"))
+
+    def test_no_match_when_not_a_git_repo(self):
+        # git rev-parse fails AND no remote — resolver returns None, no raise.
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel=None, origin=None)):
+            self.assertIsNone(resolve_repo_for_dir(CFG, "/tmp/plain-dir"))
+
+    def test_none_when_two_repos_share_a_local_path(self):
+        # Pathological config: two keys point at the same clone. Refuse to guess.
+        cfg = {"repos": {
+            "a": {"local": "/code/dup", "github": "org/a"},
+            "b": {"local": "/code/dup", "github": "org/b"},
+        }}
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/dup")):
+            self.assertIsNone(resolve_repo_for_dir(cfg, "/code/dup"))
+
+    def test_none_when_no_repos_configured(self):
+        with mock.patch.object(cwd_repo, "_git",
+                               _fake_git(toplevel="/code/x")):
+            self.assertIsNone(resolve_repo_for_dir({"repos": {}}, "/code/x"))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,147 @@
+"""Tests for the dedupe-tiers command and its tracks.py helpers (#359)."""
+import io
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import dedupe_tiers
+from lib import tracks
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _track(*, name, repo="org/repo", folder="repo", issues=None, body="", path=None,
+           tier="private"):
+    meta = {"track": name, "github": {"repo": repo}}
+    if issues is not None:
+        meta["github"]["issues"] = issues
+    return SimpleNamespace(
+        name=name,
+        path=Path(path) if path else Path(f"/tmp/notes/{folder}/{name}.md"),
+        repo=repo,
+        folder=folder,
+        meta=meta,
+        body=body,
+        tier=tier,
+    )
+
+
+def _drive(args, pairs, *, notes_root="/tmp/notes"):
+    cfg = {"notes_root": notes_root, "repos": {"repo": {"github": "org/repo"}}}
+    buf = io.StringIO()
+    with patch("commands.dedupe_tiers.load_config", return_value=cfg), \
+         patch("commands.dedupe_tiers.find_tier_duplicates", return_value=pairs), \
+         redirect_stdout(buf):
+        rc = dedupe_tiers.run(args)
+    return rc, buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# issue_refs
+# ---------------------------------------------------------------------------
+
+class TestIssueRefs(unittest.TestCase):
+    def test_unions_frontmatter_and_body(self):
+        t = _track(name="a", issues=[10, 20], body="see #20 and #30 here")
+        self.assertEqual(tracks.issue_refs(t), {10, 20, 30})
+
+    def test_empty_when_no_refs(self):
+        t = _track(name="a", issues=None, body="no refs at all")
+        self.assertEqual(tracks.issue_refs(t), set())
+
+    def test_ignores_non_int_frontmatter(self):
+        t = _track(name="a", issues=[1, "oops", None], body="")
+        self.assertEqual(tracks.issue_refs(t), {1})
+
+
+# ---------------------------------------------------------------------------
+# find_tier_duplicates pairing (helpers patched)
+# ---------------------------------------------------------------------------
+
+class TestFindTierDuplicates(unittest.TestCase):
+    def test_pairs_only_colliding_active_tracks(self):
+        shared = [_track(name="dup", tier="shared"), _track(name="only-shared", tier="shared")]
+        private = [_track(name="dup"), _track(name="only-private")]
+        cfg = {"notes_root": "/tmp/does-not-exist-xyz", "repos": {}}
+        with patch.object(tracks, "_discover_shared_tracks") as ds, \
+             patch.object(tracks, "_discover_private_tracks", return_value=private):
+            # active call returns `shared`; archive-only call returns []
+            ds.side_effect = lambda cfg, include_archive=False, archive_only=False: (
+                [] if archive_only else shared)
+            pairs = tracks.find_tier_duplicates(cfg)
+        names = [(s.name, p.name) for (s, p) in pairs]
+        self.assertEqual(names, [("dup", "dup")])
+
+
+# ---------------------------------------------------------------------------
+# command: report / apply / safety
+# ---------------------------------------------------------------------------
+
+class TestDedupeCommand(unittest.TestCase):
+    def test_no_pairs_reports_nothing(self):
+        rc, out = _drive([], [])
+        self.assertEqual(rc, 0)
+        self.assertIn("Nothing to dedupe", out)
+
+    def test_dry_run_removes_nothing(self):
+        with tempfile.TemporaryDirectory() as d:
+            pf = Path(d) / "dup.md"
+            pf.write_text("# dup\n")
+            shared = _track(name="dup", issues=[1, 2], tier="shared")
+            private = _track(name="dup", issues=[1], path=str(pf))
+            rc, out = _drive([], [(shared, private)])
+            self.assertTrue(pf.exists(), "dry run must not delete")
+        self.assertEqual(rc, 0)
+        self.assertIn("Dry run", out)
+        self.assertIn("--apply", out)
+
+    def test_apply_removes_subset_orphan(self):
+        with tempfile.TemporaryDirectory() as d:
+            pf = Path(d) / "dup.md"
+            pf.write_text("# dup\n")
+            shared = _track(name="dup", issues=[1, 2, 3], tier="shared")
+            private = _track(name="dup", issues=[1, 3], path=str(pf))
+            rc, out = _drive(["--apply"], [(shared, private)])
+            self.assertEqual(rc, 0)
+            self.assertFalse(pf.exists(), "subset orphan must be removed on --apply")
+        self.assertIn("Removed 1 private orphan", out)
+
+    def test_apply_keeps_diverged_orphan(self):
+        with tempfile.TemporaryDirectory() as d:
+            pf = Path(d) / "dup.md"
+            pf.write_text("# dup\n")
+            # private references #99 which the shared twin lacks → must be kept
+            shared = _track(name="dup", issues=[1, 2], tier="shared")
+            private = _track(name="dup", issues=[1], body="leftover #99", path=str(pf))
+            rc, out = _drive(["--apply"], [(shared, private)])
+            self.assertEqual(rc, 0)
+            self.assertTrue(pf.exists(), "diverged orphan must NOT be removed")
+        self.assertIn("#99", out)
+        self.assertIn("manual review", out)
+
+    def test_repo_filter_scopes_pairs(self):
+        a_shared = _track(name="a", repo="org/a", folder="a", issues=[1], tier="shared")
+        a_priv = _track(name="a", repo="org/a", folder="a", issues=[1])
+        b_shared = _track(name="b", repo="org/b", folder="b", issues=[1], tier="shared")
+        b_priv = _track(name="b", repo="org/b", folder="b", issues=[1])
+        rc, out = _drive(["--repo=a"], [(a_shared, a_priv), (b_shared, b_priv)])
+        self.assertEqual(rc, 0)
+        self.assertIn("a  (repo org/a)", out)
+        self.assertNotIn("org/b", out)
+
+    def test_repo_flag_without_value_is_usage_error(self):
+        rc, _ = _drive(["--repo"], [])
+        self.assertEqual(rc, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -33,6 +33,38 @@ class DetectDriftTest(unittest.TestCase):
     def test_no_table_returns_empty(self):
         self.assertEqual(detect_drift("# No table\n", [{"number": 1, "state": "CLOSED"}]), [])
 
+    # --- OPEN-side + ambiguous-body cases: pin the *intentional asymmetry* ----
+    # CLOSED is terminal → broad check (anything not-closed drifts). OPEN is not
+    # terminal → narrow check (only an explicit closed marker drifts). These
+    # guard against someone "restoring symmetry" with a `not looks_open` open-side
+    # check, which would false-positive every in-progress row.
+
+    def _body(self, status: str) -> str:
+        return ("| # | Title | Status |\n"
+                "|---|---|---|\n"
+                f"| #1 | foo | {status} |\n")
+
+    def test_drift_when_closed_in_md_open_in_github(self):
+        # OPEN-side condition (was untested): body says shipped, GitHub reopened it.
+        drift = detect_drift(self._body("✅ Shipped"), [{"number": 1, "state": "OPEN"}])
+        self.assertEqual(len(drift), 1)
+        self.assertEqual(drift[0]["github_state"], "OPEN")
+
+    def test_no_drift_when_open_in_md_open_in_github(self):
+        self.assertEqual(detect_drift(self._body("🔲 Open"), [{"number": 1, "state": "OPEN"}]), [])
+
+    def test_open_with_ambiguous_status_is_NOT_drift(self):
+        # The deliberate narrow OPEN-side: an in-progress row must not be flagged.
+        self.assertEqual(
+            detect_drift(self._body("🚧 In progress"), [{"number": 1, "state": "OPEN"}]), [])
+
+    def test_closed_with_ambiguous_status_IS_drift(self):
+        # The deliberate broad CLOSED-side: a closed issue whose row doesn't read
+        # closed (here: ambiguous) is drift.
+        drift = detect_drift(self._body("🚧 In progress"), [{"number": 1, "state": "CLOSED"}])
+        self.assertEqual(len(drift), 1)
+        self.assertEqual(drift[0]["github_state"], "CLOSED")
+
 
 if __name__ == "__main__":
     unittest.main()

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

@@ -49,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."""
 

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

@@ -151,6 +151,49 @@ class ExportRunJsonTest(unittest.TestCase):
         self.assertEqual(rc, 0)
         self.assertEqual(out["tracks"][0]["issues"], [])
 
+    # --- tier_duplicates (#361) -------------------------------------------
+
+    def _dup_track(self, *, issues, body="", path):
+        return SimpleNamespace(
+            repo=_SHARED_REPO, folder="myrepo", name="dup", path=Path(path),
+            meta={"github": {"repo": _SHARED_REPO, "issues": issues}}, body=body,
+        )
+
+    def test_tier_duplicates_empty_when_none(self):
+        """With no notes_root in cfg (mock returns {}), the field is an empty
+        list — present but quiet, so the viewer can rely on its shape."""
+        tracks = [_track("alpha", _SHARED_REPO, [1])]
+        rc, out, _ = self._run_with_mocks(tracks, _EXPORT_MAP)
+        self.assertEqual(rc, 0)
+        self.assertEqual(out["tier_duplicates"], [])
+
+    def test_tier_duplicate_subset_is_safe(self):
+        shared = self._dup_track(issues=[1, 2, 3], path="/repo/.work-plan/dup.md")
+        private = self._dup_track(issues=[1, 3], path="/notes/myrepo/dup.md")
+        with patch("commands.export.find_tier_duplicates",
+                   return_value=[(shared, private)]):
+            rc, out, _ = self._run_with_mocks([_track("a", _SHARED_REPO, [1])], _EXPORT_MAP)
+        self.assertEqual(rc, 0)
+        td = out["tier_duplicates"]
+        self.assertEqual(len(td), 1)
+        self.assertEqual(td[0]["name"], "dup")
+        self.assertEqual(td[0]["repo"], _SHARED_REPO)
+        self.assertEqual(td[0]["folder"], "myrepo")
+        self.assertTrue(td[0]["safe"])
+        self.assertEqual(td[0]["shared_path"], str(Path("/repo/.work-plan/dup.md")))
+        self.assertEqual(td[0]["private_path"], str(Path("/notes/myrepo/dup.md")))
+
+    def test_tier_duplicate_diverged_is_unsafe(self):
+        # private references #99, which the shared twin lacks → not safe to remove
+        shared = self._dup_track(issues=[1, 2], path="/repo/.work-plan/dup.md")
+        private = self._dup_track(issues=[1], body="leftover #99",
+                                  path="/notes/myrepo/dup.md")
+        with patch("commands.export.find_tier_duplicates",
+                   return_value=[(shared, private)]):
+            rc, out, _ = self._run_with_mocks([_track("a", _SHARED_REPO, [1])], _EXPORT_MAP)
+        self.assertEqual(rc, 0)
+        self.assertFalse(out["tier_duplicates"][0]["safe"])
+
     def test_visibility_included_in_output(self):
         tracks = [_track("alpha", _SHARED_REPO, [1])]
         rc, out, _ = self._run_with_mocks(tracks, _EXPORT_MAP, vis={_SHARED_REPO: "PUBLIC"})
@@ -290,6 +333,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/skills/work-plan/tests/test_register_which_repo.py

@@ -0,0 +1,22 @@
+"""which-repo is dispatchable + documented (#358/#357 Phase 1)."""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+import work_plan
+
+
+class RegisterWhichRepoTest(unittest.TestCase):
+    def test_in_subcommands(self):
+        self.assertEqual(work_plan.SUBCOMMANDS["which-repo"], "commands.which_repo")
+
+    def test_in_descriptions(self):
+        names = {row[0] for row in work_plan.DESCRIPTIONS}
+        self.assertIn("which-repo", names)
+
+
+if __name__ == "__main__":
+    unittest.main()