@stylusnexus/work-plan 2026.6.11-2 → 2026.6.13

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

@@ -0,0 +1,69 @@
+"""remove-repo subcommand — unregister a repo from config (config-only).
+
+Removes the repo block from ~/.claude/work-plan/config.yml. Deliberately leaves
+the notes folder, any tracks, and the local clone untouched — those are the
+user's data and removal here is purely a config edit. Non-interactive (the VS
+Code side confirms before invoking).
+"""
+import re
+import subprocess
+from pathlib import Path
+
+from lib.config import load_config, ConfigError, DEFAULT_CONFIG_PATH
+
+
+def run(args: list[str]) -> int:
+    # No flags — a single positional key.
+    positional = [a for a in args if a != "--"]
+    if not positional:
+        print("usage: work_plan.py remove-repo <key>")
+        return 2
+
+    key = positional[0]
+    if not re.fullmatch(r"[a-z][a-z0-9-]*", key):
+        print(f"ERROR: '{key}' is not a valid key. Use lowercase letters, digits, hyphens; must start with a letter.")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        print("\nRun ./install.sh from the toolkit root to seed your config first.")
+        return 1
+
+    repos = cfg.get("repos") or {}
+    if key not in repos:
+        print(f"ERROR: repo '{key}' not found in {DEFAULT_CONFIG_PATH}.")
+        return 1
+
+    # `key` is validated against ^[a-z][a-z0-9-]*$ above, so it is safe to
+    # interpolate into the yq path (no env() needed — del takes no value).
+    yq_expr = f"del(.repos.{key})"
+    try:
+        subprocess.run(
+            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return 1
+
+    print(f"✓ Removed repo '{key}' from {DEFAULT_CONFIG_PATH}")
+
+    # Config-only: surface what was deliberately left in place so the user knows
+    # nothing was deleted from disk.
+    print()
+    print("This was a config-only change — nothing on disk was deleted:")
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    repo_dir = notes_root / key
+    if repo_dir.exists():
+        print(f"  • Notes folder {repo_dir}/ is now orphaned — remove it manually if you don't need it.")
+    else:
+        print(f"  • Its notes folder (if any) under {notes_root}/ is left untouched.")
+    print("  • Any tracks that referenced this repo are now orphaned (clean up by hand).")
+    local = repos[key].get("local") if isinstance(repos[key], dict) else None
+    if local:
+        print(f"  • The local clone at {local} is left untouched.")
+    else:
+        print("  • Any local clone is left untouched.")
+    return 0

package/skills/work-plan/lib/export_model.py

@@ -52,7 +52,10 @@ def group_issues_by_milestone(issues, milestone_alignment=None):
     return groups
 
 
-def _issue(i: dict) -> dict:
+def normalize_issue(i: dict) -> dict:
+    """Reshape a raw gh issue row into the viewer's `Issue` shape
+    ({number,title,state,assignee,milestone}). Shared by the export and the
+    `list-open-issues` command (#282) so both emit an identical issue surface."""
     state = (i.get("state") or "OPEN").lower()
     return {
         "number": i.get("number"),
@@ -64,18 +67,27 @@ def _issue(i: dict) -> dict:
 
 
 def build_export(tracks, issues_by_track, visibility, now: str,
-                 untracked_by_repo=None) -> dict:
+                 untracked_by_repo=None, config_repos=None) -> dict:
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
     for t in tracks:
-        issues = [_issue(i) for i in issues_by_track.get(t.name, [])]
+        issues = [normalize_issue(i) for i in issues_by_track.get(t.name, [])]
         milestone_alignment = t.meta.get("milestone_alignment")
         issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")
         closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
         next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
+        track_path = getattr(t, "path", None)
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
+            # Absolute path to the track's .md, so the viewer can open it in an
+            # editor (#211). null when a track has no backing file path (the
+            # viewer disables its open-file affordance rather than erroring).
+            "path": str(track_path) if track_path else None,
+            # Config repo key (the key under `repos:` in config.yml). The Plans
+            # view passes this as `plan-status --repo=<key>` (#164), which
+            # resolves a local checkout via folder key, not github slug.
+            "folder": getattr(t, "folder", None),
             "tier": getattr(t, "tier", "private") or "private",
             "status": t.meta.get("status"),
             "launch_priority": t.meta.get("launch_priority"),
@@ -88,8 +100,13 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "issues": issues,
         })
     out["untracked"] = [
-        {"repo": repo, "issues": [_issue(r) for r in rows]}
+        {"repo": repo, "issues": [normalize_issue(r) for r in rows]}
         for repo, rows in (untracked_by_repo or {}).items()
         if rows
     ]
+    # Every CONFIGURED repo, independent of track membership (#288): so the
+    # viewer can show a registered repo even when it has no tracks/plans yet —
+    # the starting point for adding fresh tracks. Each entry:
+    # {folder, repo(slug), local, has_local, visibility}.
+    out["repos"] = list(config_repos or [])
     return out

package/skills/work-plan/lib/git_state.py

@@ -161,6 +161,28 @@ def path_last_commit_date(rel_path: str, repo_path: Path) -> Optional[datetime]:
         return None
 
 
+def paths_last_commit_date(rel_paths, repo_path: Path) -> Optional[datetime]:
+    """Timestamp of the most recent commit touching ANY of `rel_paths` (naive).
+
+    One `git log -1` over the whole pathspec, so the result is the latest commit
+    date across the set. None for empty input, a bad repo, or no commit found.
+    Used by the staleness clock (#164), which keys off a plan's declared manifest
+    files (committed) rather than the plan doc itself (gitignored, so dateless).
+    """
+    if not rel_paths:
+        return None
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    proc = _git(repo_path, "log", "-1", "--pretty=format:%cI", "--", *rel_paths)
+    if proc is None or proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        s = proc.stdout.strip().split("+")[0].split("Z")[0]
+        return datetime.fromisoformat(s)
+    except (ValueError, IndexError):
+        return None
+
+
 def path_committed_since(rel_path: str, since: date, repo_path: Path) -> bool:
     """True if `rel_path` has any commit on/around `since` or later (a datetime.date).
 

package/skills/work-plan/lib/manifest.py

@@ -14,6 +14,7 @@ PATH_RE = re.compile(r"\b(Create|Modify|Test):\s*`([^`]+)`")
 _RANGE_RE = re.compile(r":\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$")
 _CHK_DONE = re.compile(r"^\s*- \[x\]", re.I | re.M)
 _CHK_TODO = re.compile(r"^\s*- \[ \]", re.M)
+_CHK_TODO_LABEL = re.compile(r"^\s*- \[ \]\s*(.+?)\s*$", re.M)
 _DATE_RE = re.compile(r"(\d{4})-(\d{2})-(\d{2})")
 
 
@@ -48,6 +49,15 @@ def count_checkboxes(text: str) -> tuple:
     return done, done + todo
 
 
+def unchecked_checkbox_labels(text: str, cap: int = 10) -> list:
+    """Labels of unticked `- [ ]` checkboxes, in document order, capped at `cap`.
+
+    Surfaces the still-open work items of a stalled plan (#164) so the report can
+    show what's left rather than just a count.
+    """
+    return [m.group(1) for m in _CHK_TODO_LABEL.finditer(text)][:cap]
+
+
 def plan_date_from_filename(filename: str) -> Optional[date]:
     """Pull a YYYY-MM-DD prefix out of a plan filename, if present."""
     m = _DATE_RE.search(filename)

package/skills/work-plan/lib/verdict.py

@@ -11,6 +11,7 @@ SHIPPED_PCT = 80.0      # >= this % of declared files satisfied -> shipped
 PARTIAL_PCT = 20.0      # >= this % -> partial
 BOXES_STALE_PCT = 50.0  # checked-box % below this on a shipped plan -> "boxes stale"
 DEAD_DAYS = 60          # 0 files satisfied AND untouched beyond this -> dead
+STALL_DAYS = 14         # partial + manifest files cold beyond this -> stalled (#164)
 FOREIGN_RATIO = 0.7     # >= this fraction of declared paths outside repo -> foreign
 
 

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

@@ -8,6 +8,7 @@ import commands.export as export_cmd
 
 def _track(name, repo, issues, blockers=None, next_up=None, status="active", depends_on=None):
     return SimpleNamespace(name=name, repo=repo, tier="private",
+        path=Path(f"/tmp/notes/{name}.md"), folder="myrepo",
         meta={"status": status, "launch_priority": "P2", "milestone_alignment": "v1",
               "blockers": blockers or [], "next_up": next_up or [],
               "depends_on": depends_on or [],
@@ -25,11 +26,26 @@ class BuildExportTest(unittest.TestCase):
         t = out["tracks"][0]
         self.assertEqual(t["name"], "ph"); self.assertEqual(t["tier"], "private")
         self.assertEqual(t["visibility"], "PRIVATE")
+        # Absolute .md path is emitted so the viewer can open the track file
+        # (#211). Compare against str(Path(...)) so the expected separator matches
+        # the platform — str(Path) yields backslashes on Windows.
+        self.assertEqual(t["path"], str(Path("/tmp/notes/ph.md")))
+        # Config repo key surfaces for the Plans view's --repo arg (#164).
+        self.assertEqual(t["folder"], "myrepo")
         self.assertEqual(t["blockers"], [9]); self.assertEqual(t["next_up"], [1])
         self.assertEqual(t["rollup"], {"open": 1, "closed": 1})
         self.assertEqual(t["issues"][0], {"number": 1, "title": "a", "state": "open", "assignee": "@eve", "milestone": None})
         json.dumps(out)  # must be serializable
 
+    def test_path_is_null_when_track_has_no_path(self):
+        """A track object without a `path` attribute exports path=None, so the
+        viewer disables its open-file affordance instead of erroring (#211)."""
+        t0 = SimpleNamespace(name="np", repo="o/r", tier="private",
+            meta={"status": "active", "github": {"repo": "o/r", "issues": []}})
+        out = build_export([t0], {"np": []}, {"o/r": "PRIVATE"}, now="2026-06-12T00:00")
+        self.assertIsNone(out["tracks"][0]["path"])
+        json.dumps(out)  # null is serializable
+
 class BuildExportNextUpFilterTest(unittest.TestCase):
     """next_up entries whose issue is closed in the fetched payload are filtered out."""
 
@@ -292,3 +308,27 @@ class BuildExportDependsOnTest(unittest.TestCase):
         ]}
         out = build_export(tracks, issues_by_track, {"o/r": "PRIVATE"}, now="t")
         self.assertEqual(out["tracks"][0]["depends_on"], [])
+
+
+class BuildExportReposListTest(unittest.TestCase):
+    """build_export emits a top-level `repos` list of ALL configured repos,
+    independent of track membership (#288)."""
+
+    def test_emits_config_repos_including_trackless(self):
+        tracks = [_track("ph", "o/r", [1])]
+        issues_by_track = {"ph": [{"number": 1, "title": "a", "state": "OPEN", "assignees": []}]}
+        config_repos = [
+            {"folder": "r", "repo": "o/r", "local": "/x/r", "has_local": True, "visibility": "PRIVATE"},
+            {"folder": "fresh", "repo": "o/fresh", "local": None, "has_local": False, "visibility": "PUBLIC"},
+        ]
+        out = build_export(tracks, issues_by_track, {"o/r": "PRIVATE"}, now="2026-06-12T00:00",
+                           config_repos=config_repos)
+        self.assertEqual([r["folder"] for r in out["repos"]], ["r", "fresh"])
+        # the trackless repo is present even though no track references it
+        fresh = next(r for r in out["repos"] if r["folder"] == "fresh")
+        self.assertEqual(fresh["has_local"], False)
+        self.assertEqual(fresh["repo"], "o/fresh")
+
+    def test_repos_defaults_to_empty_list(self):
+        out = build_export([], {}, {}, now="2026-06-12T00:00")
+        self.assertEqual(out["repos"], [])

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

@@ -16,6 +16,8 @@ def _track(name, repo, issues, *, has_frontmatter=True, status="active"):
         name=name,
         repo=repo,
         tier="private",
+        path=Path(f"/tmp/notes/{name}.md"),
+        folder="myrepo",
         has_frontmatter=has_frontmatter,
         meta={
             "status": status,
@@ -71,6 +73,23 @@ class ExportRunJsonTest(unittest.TestCase):
         self.assertEqual(rc, 0)
         self.assertEqual(out["schema"], 1)
 
+    def test_track_file_path_is_emitted(self):
+        """The export carries each track's .md path end-to-end (#211)."""
+        tracks = [_track("alpha", _SHARED_REPO, [1])]
+        rc, out, _ = self._run_with_mocks(tracks, _EXPORT_MAP)
+        self.assertEqual(rc, 0)
+        # str(Path(...)) so the expected separator matches the platform (Windows
+        # backslashes). The path is whatever os.sep the fixture's Path produces.
+        self.assertEqual(out["tracks"][0]["path"], str(Path("/tmp/notes/alpha.md")))
+
+    def test_track_folder_key_is_emitted(self):
+        """The export carries each track's config folder key end-to-end for the
+        Plans view's `plan-status --repo=<key>` arg (#164)."""
+        tracks = [_track("alpha", _SHARED_REPO, [1])]
+        rc, out, _ = self._run_with_mocks(tracks, _EXPORT_MAP)
+        self.assertEqual(rc, 0)
+        self.assertEqual(out["tracks"][0]["folder"], "myrepo")
+
     def test_track_issues_assembled_in_declared_order(self):
         # Issues are milestone-sorted (#101): null-milestone group sorts by number.
         tracks = [_track("alpha", _SHARED_REPO, [2, 1])]

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

@@ -136,12 +136,55 @@ class InitRepoNonInteractiveTest(unittest.TestCase):
     # ------------------------------------------------------------------
 
     def test_repo_already_exists_returns_rc1(self):
-        """Key already in config.repos → rc 1, yq NOT called."""
+        """Key already in config.repos (no --update) → rc 1, yq NOT called,
+        and the message points at --update."""
         existing = {"mykey": {"github": "org/myrepo", "local": None}}
         rc, msub, out = _drive(["mykey", "--github=org/myrepo"], existing_repos=existing)
         self.assertEqual(rc, 1)
         msub.assert_not_called()
         self.assertIn("already exists", out)
+        self.assertIn("--update", out)
+
+    # ------------------------------------------------------------------
+    # --update on an existing key → updates its local path
+    # ------------------------------------------------------------------
+
+    def test_update_existing_sets_local(self):
+        """Existing key + --update --local=/new/path → yq merges local into the
+        existing block; rc 0; no 'already exists' error."""
+        existing = {"mykey": {"github": "org/myrepo"}}
+        rc, msub, out = _drive(
+            ["mykey", "--github=org/myrepo", "--local=/new/path", "--update"],
+            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")
+        # Merge expression preserves other keys via `* env(...)`.
+        expr = yq_args[2]
+        self.assertIn(".repos.mykey", expr)
+        self.assertIn("env(WP_REPO_UPDATES)", expr)
+        updates = json.loads(msub.call_args.kwargs["env"]["WP_REPO_UPDATES"])
+        self.assertEqual(updates["local"], "/new/path")
+        self.assertIn("Updated", out)
+        self.assertNotIn("already exists", out)
+
+    def test_update_nonexistent_key_falls_back_to_add(self):
+        """--update on a key NOT in config → behaves as a plain add (creates the
+        block via the add path), rc 0."""
+        rc, msub, out = _drive(
+            ["mykey", "--github=org/myrepo", "--local=/some/path", "--update"],
+            existing_repos={},
+        )
+        self.assertEqual(rc, 0)
+        msub.assert_called_once()
+        expr = msub.call_args[0][0][2]
+        # Add path uses the assignment form, not the merge form.
+        self.assertEqual(expr, ".repos.mykey = env(WP_REPO_BLOCK)")
+        block = json.loads(msub.call_args.kwargs["env"]["WP_REPO_BLOCK"])
+        self.assertEqual(block["local"], "/some/path")
 
     # ------------------------------------------------------------------
     # No key → rc 2
@@ -153,6 +196,62 @@ class InitRepoNonInteractiveTest(unittest.TestCase):
         self.assertEqual(rc, 2)
         msub.assert_not_called()
 
+    # ------------------------------------------------------------------
+    # --clear-local: sets local to null on an existing key
+    # ------------------------------------------------------------------
+
+    def test_clear_local_sets_local_null(self):
+        """--update --clear-local on an existing key → yq merges {local: null};
+        rc 0; '✓ Cleared local path' printed."""
+        existing = {"mykey": {"github": "org/myrepo", "local": "/old/path"}}
+        rc, msub, out = _drive(
+            ["mykey", "--update", "--clear-local"],
+            existing_repos=existing,
+        )
+        self.assertEqual(rc, 0)
+        msub.assert_called_once()
+        expr = msub.call_args[0][0][2]
+        self.assertIn(".repos.mykey", expr)
+        self.assertIn("env(WP_REPO_UPDATES)", expr)
+        updates = json.loads(msub.call_args.kwargs["env"]["WP_REPO_UPDATES"])
+        self.assertIn("local", updates)
+        self.assertIsNone(updates["local"])
+        # github not passed → not in the merge (other fields preserved by yq).
+        self.assertNotIn("github", updates)
+        self.assertIn("Cleared local path", out)
+
+    def test_clear_local_with_local_is_mutually_exclusive(self):
+        """--clear-local + --local=<path> → rc 2, yq NOT called."""
+        existing = {"mykey": {"github": "org/myrepo", "local": "/old/path"}}
+        rc, msub, out = _drive(
+            ["mykey", "--update", "--clear-local", "--local=/new/path"],
+            existing_repos=existing,
+        )
+        self.assertEqual(rc, 2)
+        msub.assert_not_called()
+        self.assertIn("mutually exclusive", out)
+
+    def test_clear_local_without_update_returns_rc2(self):
+        """--clear-local without --update → rc 2, yq NOT called."""
+        existing = {"mykey": {"github": "org/myrepo", "local": "/old/path"}}
+        rc, msub, out = _drive(
+            ["mykey", "--clear-local"],
+            existing_repos=existing,
+        )
+        self.assertEqual(rc, 2)
+        msub.assert_not_called()
+        self.assertIn("requires --update", out)
+
+    def test_clear_local_nonexistent_key_returns_rc1(self):
+        """--update --clear-local on a key NOT in config → rc 1, yq NOT called."""
+        rc, msub, out = _drive(
+            ["mykey", "--update", "--clear-local"],
+            existing_repos={},
+        )
+        self.assertEqual(rc, 1)
+        msub.assert_not_called()
+        self.assertIn("not found", out)
+
     # ------------------------------------------------------------------
     # Invalid key format → rc 2
     # ------------------------------------------------------------------

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

@@ -0,0 +1,83 @@
+"""Tests for the list-open-issues subcommand (#282).
+
+Mocks fetch_open_issues — runs offline, never touches the network.
+"""
+import io
+import json
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import list_open_issues
+
+
+def _row(number, title="t", state="OPEN", logins=(), milestone=None):
+    """A raw gh issue row as fetch_open_issues returns."""
+    d = {"number": number, "title": title, "state": state,
+         "assignees": [{"login": l} for l in logins]}
+    if milestone:
+        d["milestone"] = {"title": milestone}
+    return d
+
+
+def _run(args, rows):
+    with patch("commands.list_open_issues.fetch_open_issues", return_value=rows):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = list_open_issues.run(args)
+    out = buf.getvalue()
+    try:
+        parsed = json.loads(out)
+    except json.JSONDecodeError:
+        parsed = None
+    return rc, parsed
+
+
+class ListOpenIssuesTest(unittest.TestCase):
+    def test_emits_repo_and_normalized_issues(self):
+        rows = [_row(91, "Rate-limit login", "OPEN", ["eve"], "v0.6"),
+                _row(87, "Fix auth", "OPEN")]
+        rc, out = _run(["--repo=o/r"], rows)
+        self.assertEqual(rc, 0)
+        self.assertEqual(out["repo"], "o/r")
+        # Same Issue shape as the export (number/title/state/assignee/milestone).
+        self.assertEqual(
+            out["issues"][0],
+            {"number": 91, "title": "Rate-limit login", "state": "open",
+             "assignee": "@eve", "milestone": "v0.6"},
+        )
+        self.assertEqual(out["issues"][1],
+                         {"number": 87, "title": "Fix auth", "state": "open",
+                          "assignee": "—", "milestone": None})
+
+    def test_exclude_filters_given_numbers(self):
+        rows = [_row(1), _row(2), _row(3)]
+        rc, out = _run(["--repo=o/r", "--exclude=1,3"], rows)
+        self.assertEqual(rc, 0)
+        self.assertEqual([i["number"] for i in out["issues"]], [2])
+
+    def test_exclude_tolerates_blanks_and_nonnumeric(self):
+        rows = [_row(1), _row(2)]
+        rc, out = _run(["--repo=o/r", "--exclude=1, ,x,"], rows)
+        self.assertEqual(rc, 0)
+        self.assertEqual([i["number"] for i in out["issues"]], [2])
+
+    def test_missing_repo_is_usage_error(self):
+        rc, out = _run([], [])
+        self.assertEqual(rc, 2)
+        self.assertIn("error", out)
+
+    def test_empty_fetch_yields_empty_issue_list(self):
+        # fetch_open_issues returns [] on a bad/unreachable repo — not an error.
+        rc, out = _run(["--repo=o/r"], [])
+        self.assertEqual(rc, 0)
+        self.assertEqual(out, {"repo": "o/r", "issues": []})
+
+
+if __name__ == "__main__":
+    unittest.main()