@stylusnexus/work-plan 2026.6.11-2 → 2026.6.13

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

@@ -0,0 +1,219 @@
+"""Tests for the plan-status staleness clock (#164).
+
+The clock keys off a plan's DECLARED manifest files (which get committed) — not
+the plan doc's own git date, which is null because plan docs are gitignored.
+All git is mocked; these run offline.
+"""
+import sys
+import unittest
+from datetime import date, datetime
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from lib import git_state
+from lib import manifest
+from lib import verdict as verdict_mod
+from commands import plan_status
+
+
+class TestPathsLastCommitDate(unittest.TestCase):
+    def test_returns_max_date_over_paths(self):
+        proc = mock.Mock(returncode=0, stdout="2026-06-10T12:00:00+00:00")
+        with mock.patch.object(Path, "exists", return_value=True), \
+                mock.patch.object(git_state, "_git", return_value=proc):
+            got = git_state.paths_last_commit_date(
+                ["a.py", "b.py"], Path("/repo"))
+        self.assertEqual(got, datetime(2026, 6, 10, 12, 0, 0))
+
+    def test_empty_paths_is_none(self):
+        with mock.patch.object(Path, "exists", return_value=True), \
+                mock.patch.object(git_state, "_git") as g:
+            self.assertIsNone(git_state.paths_last_commit_date([], Path("/repo")))
+            g.assert_not_called()
+
+    def test_empty_stdout_is_none(self):
+        proc = mock.Mock(returncode=0, stdout="")
+        with mock.patch.object(Path, "exists", return_value=True), \
+                mock.patch.object(git_state, "_git", return_value=proc):
+            self.assertIsNone(
+                git_state.paths_last_commit_date(["a.py"], Path("/repo")))
+
+
+class TestStallDaysConstant(unittest.TestCase):
+    def test_default_is_14(self):
+        self.assertEqual(verdict_mod.STALL_DAYS, 14)
+
+
+class TestUncheckedCheckboxLabels(unittest.TestCase):
+    def test_captures_unticked_labels_in_order(self):
+        text = (
+            "- [x] Phase 1 — git helper\n"
+            "- [x] Phase 2 — manifest\n"
+            "- [ ] Phase 4 — tests\n"
+            "- [ ] Phase 5 — docs\n"
+        )
+        self.assertEqual(
+            manifest.unchecked_checkbox_labels(text),
+            ["Phase 4 — tests", "Phase 5 — docs"],
+        )
+
+    def test_cap_limits_results(self):
+        text = "\n".join(f"- [ ] item {i}" for i in range(20))
+        got = manifest.unchecked_checkbox_labels(text)
+        self.assertEqual(len(got), 10)
+        self.assertEqual(got[0], "item 0")
+
+
+class _FakePath:
+    def __init__(self, name):
+        self.name = name
+
+
+class _Doc:
+    @classmethod
+    def make(cls, rel="plans/p.md", kind="plan", name="2026-05-01-p.md"):
+        d = cls.__new__(cls)
+        d.rel = rel
+        d.kind = kind
+        d.path = _FakePath(name)
+        return d
+
+
+def _decl(path):
+    return manifest.DeclaredPath(kind="create", path=path)
+
+
+class TestEvaluateStaleness(unittest.TestCase):
+    """The staleness ladder fires only for partial verdicts and keys off the
+    manifest files' commit date, not the plan doc's own (gitignored) date."""
+
+    def setUp(self):
+        self.today = date(2026, 6, 12)
+        self.partial = verdict_mod.Verdict("partial", "\U0001f7e1", "files")
+        self.decls = [_decl("src/a.py"), _decl("src/b.py")]
+
+    def _evaluate(self, manifest_date, on_disk, verdict=None, text="body"):
+        """Run _evaluate with manifest.* / git_state.* / classify mocked.
+
+        manifest_date: what paths_last_commit_date returns.
+        on_disk: which declared paths _declared_paths_on_disk reports present.
+        """
+        v = verdict or self.partial
+        doc = _Doc.make()
+        with mock.patch.object(plan_status, "_read", return_value=text), \
+                mock.patch.object(manifest, "parse_declared_paths", return_value=self.decls), \
+                mock.patch.object(manifest, "plan_date_from_filename", return_value=None), \
+                mock.patch.object(manifest, "score_manifest",
+                                  return_value=manifest.ManifestScore(2, 1, {})), \
+                mock.patch.object(manifest, "count_checkboxes", return_value=(1, 4)), \
+                mock.patch.object(manifest, "out_of_tree_ratio", return_value=0.0), \
+                mock.patch.object(manifest, "unchecked_checkbox_labels",
+                                  return_value=["do x"]), \
+                mock.patch.object(plan_status, "_declared_paths_on_disk",
+                                  return_value=on_disk), \
+                mock.patch.object(git_state, "path_last_commit_date", return_value=None), \
+                mock.patch.object(git_state, "paths_last_commit_date",
+                                  return_value=manifest_date), \
+                mock.patch.object(verdict_mod, "classify", return_value=v):
+            return plan_status._evaluate(doc, Path("/repo"), self.today, 60, 14)
+
+    def test_partial_cold_is_stalled(self):
+        cold = datetime(2026, 5, 1, 12, 0, 0)  # 42 days before today
+        row = self._evaluate(cold, ["src/a.py", "src/b.py"])
+        self.assertTrue(row["stalled"])
+        self.assertEqual(row["manifest_last_touched"], "2026-05-01")
+
+    def test_partial_warm_is_not_stalled(self):
+        warm = datetime(2026, 6, 10, 12, 0, 0)  # 2 days before today
+        row = self._evaluate(warm, ["src/a.py"])
+        self.assertFalse(row["stalled"])
+
+    def test_partial_no_files_on_disk_is_not_stalled(self):
+        row = self._evaluate(None, [])
+        self.assertFalse(row["stalled"])
+        self.assertIsNone(row["manifest_last_touched"])
+
+    def test_doc_uncommitted_but_manifest_committed_is_stalled(self):
+        # path_last_commit_date (doc) is None, but manifest committed 42d ago.
+        cold = datetime(2026, 5, 1, 12, 0, 0)
+        row = self._evaluate(cold, ["src/a.py"])
+        self.assertTrue(row["stalled"])
+        self.assertIsNone(row["last_touched"])  # doc date stays None
+
+    def test_present_but_never_committed_is_stalled(self):
+        # files exist on disk but manifest date is None -> never committed
+        row = self._evaluate(None, ["src/a.py"])
+        self.assertTrue(row["stalled"])
+
+    def test_emits_unchecked_items_and_stall_days(self):
+        row = self._evaluate(datetime(2026, 6, 10), ["src/a.py"])
+        self.assertEqual(row["unchecked_items"], ["do x"])
+        self.assertEqual(row["stall_days"], 14)
+
+    def test_non_partial_is_never_stalled(self):
+        shipped = verdict_mod.Verdict("shipped", "✅", "files")
+        row = self._evaluate(None, [], verdict=shipped)
+        self.assertFalse(row["stalled"])
+
+
+class TestResolveStallDays(unittest.TestCase):
+    def test_known_flag_set_includes_stall_days(self):
+        self.assertIn("--stall-days", plan_status.KNOWN)
+
+    def test_flag_beats_config_beats_default(self):
+        with mock.patch.object(plan_status.config_mod, "load_config",
+                               return_value={"stall_days": 30}):
+            self.assertEqual(
+                plan_status._resolve_stall_days({"--stall-days": "45"}), 45)
+
+    def test_config_beats_default(self):
+        with mock.patch.object(plan_status.config_mod, "load_config",
+                               return_value={"stall_days": 30}):
+            self.assertEqual(plan_status._resolve_stall_days({}), 30)
+
+    def test_default_when_unset(self):
+        with mock.patch.object(plan_status.config_mod, "load_config",
+                               return_value={}):
+            self.assertEqual(plan_status._resolve_stall_days({}), 14)
+
+    def test_non_integer_flag_falls_through(self):
+        with mock.patch.object(plan_status.config_mod, "load_config",
+                               return_value={}):
+            self.assertEqual(
+                plan_status._resolve_stall_days({"--stall-days": "abc"}), 14)
+
+
+class TestDeclaredPathsOnDiskGuards(unittest.TestCase):
+    """A junk declared path ('/'), a directory, or an out-of-tree '../x' must be
+    excluded — otherwise they poison `git log -- <paths>` and falsely stall an
+    actively-built plan (regression from the smoke test for #164)."""
+
+    def test_excludes_root_slash_dirs_and_escapes_keeps_real_files(self):
+        import tempfile, os
+        from lib.manifest import DeclaredPath
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            (root / "src").mkdir()
+            real = "src/a.py"
+            (root / real).write_text("x")
+            # a sibling file outside the repo root
+            outside = Path(td).parent / "escape_probe_164.py"
+            try:
+                outside.write_text("x")
+                decls = [
+                    DeclaredPath(kind="create", path=real),       # real file -> kept
+                    DeclaredPath(kind="create", path="/"),        # resolves to FS root dir -> dropped
+                    DeclaredPath(kind="create", path="src"),      # a directory -> dropped
+                    DeclaredPath(kind="modify", path=f"../{outside.name}"),  # out-of-tree -> dropped
+                ]
+                got = plan_status._declared_paths_on_disk(decls, root)
+                self.assertEqual(got, [real])
+            finally:
+                if outside.exists():
+                    outside.unlink()
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,138 @@
+"""Cross-repo duplicate-slug isolation in reconcile (#255).
+
+Identical track slugs in DIFFERENT repos are explicitly supported. Reconcile's
+in-flight state must be keyed by a per-track identity (repo, path), not by slug
+— otherwise a later same-slug track's fetch overwrites the earlier one's, and
+under `--all --yes` issues from one repo get written into the same-named track
+in ANOTHER repo (membership corruption).
+
+All gh calls are mocked; tests run offline. The fake `gh` here is REPO-AWARE
+(unlike the shared move harness) so two same-slug tracks in different repos can
+return different labeled issues.
+"""
+import json
+import sys
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import reconcile
+
+
+def _track(*, slug, repo, issues=None):
+    # Path embeds the repo so two same-slug tracks have distinct file paths,
+    # mirroring how discover_tracks lays out per-repo note dirs.
+    safe_repo = repo.replace("/", "_")
+    return SimpleNamespace(
+        name=slug,
+        path=Path(f"/tmp/fake/{safe_repo}/{slug}.md"),
+        body="# fake",
+        meta={"track": slug, "status": "active",
+              "github": {"repo": repo, "issues": list(issues or [])}},
+        has_frontmatter=True,
+        repo=repo,
+    )
+
+
+class _RepoAwareHarness:
+    """Drives reconcile --all where labeled issues depend on BOTH repo and label.
+
+    `labeled` maps (repo, label) -> list of issue dicts that
+    `gh issue/pr list --repo <repo> --label <label>` should return.
+    """
+
+    def __init__(self, tracks, labeled):
+        self.tracks = tracks
+        self.labeled = labeled
+        self.writes = []  # (path_str, issues) per write_file call
+
+    def _fake_run(self, argv, *a, **kw):
+        out = []
+        if "--label" in argv and argv[1] == "issue":  # count issues once, not PRs
+            repo = argv[argv.index("--repo") + 1]
+            lab = argv[argv.index("--label") + 1]
+            out = self.labeled.get((repo, lab), [])
+        return MagicMock(returncode=0, stdout=json.dumps(out), stderr="")
+
+    def _fake_write(self, path, meta, body):
+        self.writes.append((str(path), list(meta.get("github", {}).get("issues") or [])))
+
+    def run(self, extra_args=None):
+        cfg = {"notes_root": "/tmp/n"}
+        with patch("commands.reconcile.subprocess.run", side_effect=self._fake_run), \
+             patch("commands.reconcile.load_config", return_value=cfg), \
+             patch("commands.reconcile.discover_tracks", return_value=self.tracks), \
+             patch("commands.reconcile.needs_confirm", return_value=False), \
+             patch("commands.reconcile.write_file", side_effect=self._fake_write), \
+             patch("commands.reconcile.prompt_input", return_value="y"):
+            rc = reconcile.run(["--all"] + (extra_args or []))
+        return rc
+
+
+class DupSlugCrossRepoTest(unittest.TestCase):
+    def test_adds_land_in_the_correct_repo_track(self):
+        """Two tracks share slug 'core' across repos o/a and o/b. Each repo
+        labels a DIFFERENT issue. Under --all --yes, each issue must land in
+        its OWN repo's track — never bleed into the same-named sibling."""
+        a = _track(slug="core", repo="o/a", issues=[])
+        b = _track(slug="core", repo="o/b", issues=[])
+        labeled = {
+            ("o/a", "track/core"): [{"number": 11, "title": "a-issue", "state": "OPEN"}],
+            ("o/b", "track/core"): [{"number": 22, "title": "b-issue", "state": "OPEN"}],
+        }
+        h = _RepoAwareHarness([a, b], labeled)
+        rc = h.run(extra_args=["--yes"])
+        self.assertEqual(rc, 0)
+        writes = dict(h.writes)
+        # Key off each track's real Path string (backslashes on Windows), not a
+        # hardcoded POSIX literal — the collision is the slug, not the path.
+        self.assertEqual(writes[str(a.path)], [11])
+        self.assertEqual(writes[str(b.path)], [22])
+
+    def test_failed_fetch_does_not_corrupt_same_slug_sibling(self):
+        """If repo o/a's fetch is intact but o/b's is independent, the second
+        track's results must not overwrite the first's. Here o/a adds #11 and
+        o/b adds #22; pre-fix, the shared 'core' key meant the second fetch
+        clobbered the first and #11 was lost / mis-routed."""
+        a = _track(slug="core", repo="o/a", issues=[11])  # already has #11
+        b = _track(slug="core", repo="o/b", issues=[])
+        labeled = {
+            # o/a still labels #11 (no change → no write expected for a)
+            ("o/a", "track/core"): [{"number": 11, "title": "a", "state": "OPEN"}],
+            # o/b newly labels #99
+            ("o/b", "track/core"): [{"number": 99, "title": "b", "state": "OPEN"}],
+        }
+        h = _RepoAwareHarness([a, b], labeled)
+        rc = h.run(extra_args=["--yes"])
+        self.assertEqual(rc, 0)
+        writes = dict(h.writes)
+        # o/a unchanged → not written. o/b gains #99 only — NOT #11.
+        self.assertNotIn(str(a.path), writes)
+        self.assertEqual(writes[str(b.path)], [99])
+
+    def test_no_cross_repo_move_between_same_slug_tracks(self):
+        """A move only fires within ONE repo. #50 sits in o/a's 'core'
+        frontmatter and is labeled for o/b's 'core' — different repos, so it
+        must stay a FLAG on o/a, not move across the repo boundary."""
+        a = _track(slug="core", repo="o/a", issues=[50])
+        b = _track(slug="core", repo="o/b", issues=[])
+        labeled = {
+            ("o/a", "track/core"): [],  # #50 lost its label in o/a
+            ("o/b", "track/core"): [{"number": 50, "title": "x", "state": "OPEN"}],
+        }
+        h = _RepoAwareHarness([a, b], labeled)
+        rc = h.run(extra_args=["--yes"])
+        self.assertEqual(rc, 0)
+        writes = dict(h.writes)
+        # o/a keeps #50 (no same-repo move target) → not rewritten.
+        self.assertNotIn(str(a.path), writes)
+        # o/b ADDs #50 because it now carries o/b's label — legitimate, in-repo.
+        self.assertEqual(writes.get(str(b.path)), [50])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -160,6 +160,81 @@ class CanonicalRederiveTest(unittest.TestCase):
         self.assertIn("## Notes\n\nkeep me", mw.call_args[0][2])
 
 
+class PartialFetchTest(unittest.TestCase):
+    """A degraded GitHub fetch must never overwrite valid rows with
+    '(not fetched)'. The track is skipped, left untouched, and the run exits
+    nonzero so --yes / hygiene callers see the degradation (#256)."""
+
+    def test_partial_fetch_skips_track_and_preserves_rows(self):
+        """One of several frontmatter issues missing → no write, rc=1, the
+        existing table is left exactly as it was."""
+        existing = [_gh(1, "first"), _gh(2, "second")]
+        track = _track(name="t", repo="o/r", issues=[1, 2, 3],
+                       body=_canon_body(existing + [_gh(3, "third")]))
+        original_body = track.body
+        # #3 fails to come back from the fetch.
+        rc, mw, out = _drive(track, existing, ["t", "--yes"])
+        self.assertEqual(rc, 1)
+        mw.assert_not_called()
+        self.assertEqual(track.body, original_body)
+        self.assertNotIn("(not fetched)", out)
+        self.assertIn("#3", out)
+        self.assertNotIn("All tracks in sync.", out)
+
+    def test_total_fetch_failure_skips_track(self):
+        """Fetch returns nothing (GitHub unreachable) → track skipped, rc=1,
+        no write, table untouched."""
+        existing = [_gh(1, "first"), _gh(2, "second")]
+        track = _track(name="t", repo="o/r", issues=[1, 2],
+                       body=_canon_body(existing))
+        rc, mw, out = _drive(track, [], ["t", "--yes"])
+        self.assertEqual(rc, 1)
+        mw.assert_not_called()
+        self.assertIn("no issues", out)
+
+    def test_healthy_track_still_refreshes_alongside_degraded(self):
+        """In an --all batch, a complete-fetch track writes normally while a
+        degraded track is skipped; the run still exits nonzero overall."""
+        good_existing = [_gh(1, "first", "OPEN")]
+        good = _track(name="good", repo="o/r", issues=[1],
+                      body=_canon_body(good_existing))
+        bad = _track(name="bad", repo="o/r", issues=[5, 6],
+                     body=_canon_body([_gh(5, "fifth"), _gh(6, "sixth")]))
+
+        # good: #1 fetched (and flipped to CLOSED so there's a write); bad: #6 missing.
+        fetched = [_gh(1, "first", "CLOSED"), _gh(5, "fifth")]
+        cfg = {"notes_root": "/tmp/fake"}
+        with patch("commands.refresh_md.load_config", return_value=cfg), \
+             patch("commands.refresh_md.discover_tracks", return_value=[good, bad]), \
+             patch("commands.refresh_md.fetch_issues", return_value=fetched), \
+             patch("commands.refresh_md.write_file") as mw:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = refresh_md.run(["--all", "--yes"])
+        out = buf.getvalue()
+        self.assertEqual(rc, 1)
+        # Only the healthy track is written.
+        self.assertEqual(mw.call_count, 1)
+        written_path = mw.call_args[0][0]
+        self.assertEqual(written_path.name, "good.md")
+        self.assertIn("#6", out)  # degraded track's missing issue is reported
+
+    def test_table_only_number_absent_from_frontmatter_does_not_gate(self):
+        """A number that appears in the body table but NOT in frontmatter
+        doesn't feed the rebuild, so a fetch miss on it is harmless — the track
+        still refreshes (rc=0)."""
+        # Frontmatter membership is [1, 2]; the body also references #99, which
+        # is not in frontmatter. #99 is not fetched, but must not block.
+        existing = [_gh(1, "first", "OPEN"), _gh(2, "second")]
+        body = _canon_body(existing) + "\nSee also #99 for context.\n"
+        track = _track(name="t", repo="o/r", issues=[1, 2], body=body)
+        rc, mw, out = _drive(track, [_gh(1, "first", "CLOSED"), _gh(2, "second")],
+                             ["t", "--yes"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertNotIn("(not fetched)", mw.call_args[0][2])
+
+
 class NarrativeTableTest(unittest.TestCase):
     """Tracks with NO canonical marker keep the conservative in-place behavior."""
 

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

@@ -0,0 +1,77 @@
+"""Tests for the non-interactive remove-repo command (#290).
+
+Covers:
+- Removing an existing key → yq called with del(.repos.<key>); rc 0.
+- Missing key (not in config) → rc 1, yq NOT called.
+- Invalid key format → rc 2, yq NOT called.
+- No positional key → rc 2.
+"""
+import io
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import remove_repo
+
+
+def _make_cfg(*, notes_root="/tmp/fake-notes", repos=None):
+    return {"notes_root": notes_root, "repos": repos or {}}
+
+
+def _drive(args, *, existing_repos=None):
+    cfg = _make_cfg(repos=existing_repos or {})
+    mock_proc = MagicMock(returncode=0, stdout="", stderr="")
+    with patch("commands.remove_repo.load_config", return_value=cfg), \
+         patch("commands.remove_repo.subprocess.run", return_value=mock_proc) as msub, \
+         patch("pathlib.Path.exists", return_value=False):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = remove_repo.run(args)
+    return rc, msub, buf.getvalue()
+
+
+class RemoveRepoTest(unittest.TestCase):
+
+    def test_removes_existing_key(self):
+        """Existing key → yq del(.repos.<key>) called; rc 0; '✓ Removed' printed."""
+        existing = {"mykey": {"github": "org/myrepo", "local": "/some/path"}}
+        rc, msub, out = _drive(["mykey"], existing_repos=existing)
+        self.assertEqual(rc, 0)
+        msub.assert_called_once()
+        yq_args = msub.call_args[0][0]
+        self.assertEqual(yq_args[0], "yq")
+        self.assertEqual(yq_args[1], "-i")
+        self.assertEqual(yq_args[2], "del(.repos.mykey)")
+        self.assertIn("✓ Removed", out)
+        # Config-only note surfaces the untouched local clone.
+        self.assertIn("config-only", out)
+
+    def test_missing_key_returns_rc1(self):
+        """Key not in config.repos → rc 1, yq NOT called."""
+        existing = {"otherkey": {"github": "org/other"}}
+        rc, msub, out = _drive(["mykey"], existing_repos=existing)
+        self.assertEqual(rc, 1)
+        msub.assert_not_called()
+        self.assertIn("not found", out)
+
+    def test_invalid_key_format_returns_rc2(self):
+        """Uppercase key → rc 2, yq NOT called (validated before load)."""
+        rc, msub, out = _drive(["MyKey"], existing_repos={"MyKey": {}})
+        self.assertEqual(rc, 2)
+        msub.assert_not_called()
+        self.assertIn("not a valid key", out)
+
+    def test_no_key_returns_rc2(self):
+        """No positional key → rc 2, yq NOT called."""
+        rc, msub, out = _drive([], existing_repos={})
+        self.assertEqual(rc, 2)
+        msub.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/work-plan/work_plan.py

@@ -38,6 +38,7 @@ SUBCOMMANDS = {
     "list": "commands.list_cmd",
     "init": "commands.init",
     "init-repo": "commands.init_repo",
+    "remove-repo": "commands.remove_repo",
     "suggest-priorities": "commands.suggest_priorities",
     "group": "commands.group",
     "auto-triage": "commands.auto_triage",
@@ -51,6 +52,7 @@ SUBCOMMANDS = {
     "plan-status": "commands.plan_status",
     "--plan-status": "commands.plan_status",  # flag-style alias
     "export": "commands.export",
+    "list-open-issues": "commands.list_open_issues",
     "set": "commands.set_field",
     "new-track": "commands.new_track",
     "rename-track": "commands.rename_track",
@@ -101,10 +103,14 @@ DESCRIPTIONS = [
      "Add frontmatter to an existing track .md file.",
      "After moving/creating a new .md file in Project Notes/<repo>/ that has no frontmatter.",
      "/work-plan init '<notes_root>/<repo-key>/foo.md'"),
-    ("init-repo", "<key> --github=<org/repo> [--local=<path>]",
-     "Bootstrap a new repo: create <notes_root>/<key>/archive/{shipped,abandoned}/ and add the repo block to your config.",
-     "When you start tracking a new GitHub repo. Replaces the old 'copy the example folder' setup.",
+    ("init-repo", "<key> --github=<org/repo> [--local=<path>] [--update [--clear-local]]",
+     "Bootstrap a new repo: create <notes_root>/<key>/archive/{shipped,abandoned}/ and add the repo block to your config. With --update on an existing key, change its local/github; --update --clear-local drops the saved local path (keeps github + other fields). --clear-local and --local are mutually exclusive.",
+     "When you start tracking a new GitHub repo. Replaces the old 'copy the example folder' setup. Use --update --clear-local to forget a stale checkout path without removing the repo.",
      "/work-plan init-repo myproject --github=your-org/myproject"),
+    ("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 — if a notes folder or tracks reference it they're now orphaned and can be cleaned up by hand.",
+     "When you stop tracking a repo and want it out of the sidebar/brief without deleting your notes. Completes the add/update/remove trio with init-repo.",
+     "/work-plan remove-repo myproject"),
     ("suggest-priorities", "[--repo=<folder>] [--apply]",
      "AI-assisted batch backfill of priority/PN labels.",
      "ONE-TIME setup, or whenever a wave of new unlabeled issues piles up.",
@@ -141,6 +147,10 @@ DESCRIPTIONS = [
      "Emit the viewer-ready JSON read surface (schema 1): every frontmatter'd track with repo, tier, status, visibility, blockers, next_up, an open/closed rollup, and per-issue state/assignee/milestone. Read-only; derives live from gh. Consumed by the VS Code extension.",
      "When a tool (the VS Code viewer, or any script) needs structured track state instead of the human-facing brief/orient text.",
      "/work-plan export --json"),
+    ("list-open-issues", "--repo=<owner/name> [--exclude=<csv-issue-numbers>]",
+     "Emit a repo's OPEN issues as JSON ({repo, issues:[{number,title,state,assignee,milestone}]}) — the same issue shape as export. Read-only; derives live from gh. --repo takes a bare org/repo slug; --exclude drops the given issue numbers (the viewer passes a track's current issues so already-slotted ones don't reappear). Unlike export's `untracked`, this includes issues tracked by OTHER tracks, since those are valid slot targets.",
+     "When the VS Code viewer's Slot command needs the repo's open issues as a pick-list (the per-track export can't supply issues not yet in the track).",
+     "/work-plan list-open-issues --repo=stylusnexus/work-plan-toolkit --exclude=87,91"),
     ("set", "<track | track@repo> field=value [field=value …] [--repo=<key>] [--confirm=<token>]",
      "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.",
@@ -258,7 +268,7 @@ def main(argv: list[str]) -> int:
 # (Flag aliases like --brief/--plan-status normalise by stripping leading dashes.)
 _READONLY_SUBCOMMANDS = frozenset({
     "brief", "orient", "where-was-i", "list", "coverage", "duplicates",
-    "plan-status", "export", "notes-vcs",
+    "plan-status", "export", "list-open-issues", "notes-vcs",
     # plan-branch manages its OWN commits on the plan branch (init seeds +
     # commits the skeleton itself); the auto-commit hooks must not also fire.
     "plan-branch",