@stylusnexus/work-plan 2026.6.11 → 2026.6.13-2

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/commands/set_field.py

@@ -1,12 +1,13 @@
 """set subcommand — guarded edit of a track's frontmatter scalar/list fields."""
 import json
-from lib.config import load_config, ConfigError
+import sys
+from lib.config import load_config, ConfigError, resolve_local_path_for_folder
 from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
 from lib.frontmatter import write_file
 from lib.write_guard import needs_confirm, make_token, valid_token
 from lib.prompts import parse_flags
 
-ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up", "depends_on"}
+ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up", "depends_on", "plan"}
 LIST_FIELDS = {"blockers", "next_up"}
 STATUSES = {"active", "in-progress", "blocked", "parked", "shipped", "abandoned"}
 
@@ -39,6 +40,10 @@ def run(args: list[str]) -> int:
                 print(f"ERROR: {k} takes comma-separated integers (got {v!r})"); return 2
         elif k == "status" and v not in STATUSES:
             print(f"ERROR: status {v!r} invalid (allowed: {sorted(STATUSES)})"); return 2
+        elif k == "plan":
+            # Repo-relative path to the track's plan/spec doc (#285). Empty value
+            # clears the link. Stored as a scalar string; validated (advisory) below.
+            parsed[k] = v.strip()
         else:
             parsed[k] = v
     try:
@@ -58,7 +63,21 @@ def run(args: list[str]) -> int:
                           "reason": f"{track.repo} is PUBLIC (or visibility unknown); edit will be written there.",
                           "token": make_token(track.repo, track.name)}))
         return 0
+    # An empty `plan=` clears the link rather than writing `plan: ""` (#285).
+    if "plan" in parsed and parsed["plan"] == "":
+        parsed.pop("plan")
+        track.meta.pop("plan", None)
+    # Advisory validation: a non-empty plan path that doesn't resolve to a file in
+    # the track's repo checkout is saved anyway (the doc may not exist yet, or the
+    # repo may have no local clone) but flagged so a typo is caught early.
+    if parsed.get("plan") and track.folder:
+        local = resolve_local_path_for_folder(track.folder, cfg)
+        if local and local.exists() and not (local / parsed["plan"]).is_file():
+            print(f"WARN: plan path {parsed['plan']!r} does not resolve to a file "
+                  f"under {local} — link saved anyway.", file=sys.stderr)
+
     track.meta.update(parsed)
     write_file(track.path, track.meta, track.body)
-    print(f"✓ set {', '.join(parsed)} on {track.name}")
+    fields = ", ".join(parsed) if parsed else "plan (cleared)"
+    print(f"✓ set {fields} on {track.name}")
     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,29 @@ 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,
+                 plan_by_track=None) -> dict:
+    plan_by_track = plan_by_track or {}
     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"),
@@ -86,10 +100,19 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "depends_on": list(t.meta.get("depends_on") or []),
             "rollup": {"open": opened, "closed": len(issues) - opened},
             "issues": issues,
+            # The track's declared plan/spec doc + its execution badge (#285), or
+            # null when the track declares no `plan:`. `{rel, resolved:false}` when
+            # the link can't be resolved (no local clone / file absent).
+            "plan": plan_by_track.get(t.name),
         })
     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/github_state.py

@@ -28,6 +28,69 @@ def _valid_repo(repo: str) -> bool:
     return bool(repo) and _REPO_RE.match(repo) is not None
 
 
+def close_issue(repo: str, number: int, reason=None, comment=None) -> tuple:
+    """Close a GitHub issue via `gh issue close` — the toolkit's ONLY
+    GitHub-mutating call (#305). Everything else here is read-only.
+
+    Returns (ok, message). `reason` ∈ {completed, not_planned} maps to
+    `--reason`; `comment` (if given) posts a closing comment. The issue number
+    is coerced to str for argv (never shell-interpolated), and `repo` is
+    validated as owner/name first, so neither can inject. Never raises — a gh
+    failure (already-closed, no write access, network, not-found) comes back as
+    (False, <gh stderr>)."""
+    if not _valid_repo(repo):
+        return (False, f"invalid repo '{repo}'")
+    args = ["gh", "issue", "close", str(int(number)), "--repo", repo]
+    if reason in ("completed", "not_planned"):
+        args += ["--reason", reason]
+    if comment:
+        args += ["--comment", str(comment)]
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except Exception as e:
+        return (False, f"gh issue close failed: {e}")
+    if proc.returncode != 0:
+        return (False, (proc.stderr or proc.stdout or "gh issue close failed").strip())
+    return (True, (proc.stdout or f"closed #{number}").strip())
+
+
+def gh_auth_status() -> dict:
+    """Probe `gh` authentication so callers can fast-fail instead of silently
+    degrading (#auth). Returns:
+
+        {"gh_present": bool, "authenticated": bool,
+         "user": str | None, "error": str | None}
+
+    Distinguishes the two failure modes the UI must handle differently:
+    `gh` not installed (`gh_present` False — fix is "install gh") vs installed
+    but not logged in (`authenticated` False — fix is "gh auth login").
+
+    Never raises. `gh auth status` exits 0 when at least one host is logged in,
+    non-zero otherwise; it prints the human status to STDERR. We parse a
+    best-effort `user` from that text but treat the EXIT CODE as authoritative."""
+    try:
+        proc = subprocess.run(
+            ["gh", "auth", "status"],
+            capture_output=True, text=True, timeout=GH_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return {"gh_present": False, "authenticated": False,
+                "user": None, "error": "gh CLI not found on PATH"}
+    except Exception as e:  # timeout / OS error — gh present but unusable now
+        return {"gh_present": True, "authenticated": False,
+                "user": None, "error": f"gh auth status failed: {e}"}
+
+    blob = f"{proc.stdout}\n{proc.stderr}"
+    authenticated = proc.returncode == 0
+    # `gh auth status` prints e.g. "✓ Logged in to github.com account USER" or
+    # the older "Logged in to github.com as USER". Match either phrasing.
+    m = re.search(r"Logged in to \S+ (?:account|as) (\S+)", blob)
+    user = m.group(1) if (authenticated and m) else None
+    error = None if authenticated else (blob.strip() or "not logged in to GitHub")
+    return {"gh_present": True, "authenticated": authenticated,
+            "user": user, "error": error}
+
+
 def fetch_issue(repo: str, number: int) -> Optional[dict]:
     """Fetch a single issue via gh. Returns parsed dict on success, None on failure.
     Never raises — a missing `gh` binary, a timeout, or a bad repo yields None."""

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)
@@ -82,6 +92,24 @@ def out_of_tree_ratio(decls: list, repo_root) -> float:
     return out / len(decls)
 
 
+def offtree_declared_paths(decls: list, repo_root) -> list:
+    """Declared paths that resolve OUTSIDE repo_root — absolute paths, `~`-rooted,
+    `..`-escapes, or junk like a literal `/` (#286 slice 3, surfaced read-only).
+
+    Distinct from "not yet created": these can never be satisfied by THIS repo,
+    so they silently drag the file score down and usually mean a typo or a
+    misfiled plan. Returned de-duped in first-declared order so the viewer can
+    flag them; the toolkit never auto-edits the manifest (that'd be a body
+    write, which #286 forbids). Below `out_of_tree_ratio`'s FOREIGN_RATIO the
+    🧳 verdict doesn't fire, so without this they'd be invisible."""
+    out, seen = [], set()
+    for d in decls:
+        if d.path not in seen and not is_in_tree(d.path, repo_root):
+            seen.add(d.path)
+            out.append(d.path)
+    return out
+
+
 @dataclass
 class ManifestScore:
     total: int

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

@@ -0,0 +1,71 @@
+"""Shared frontmatter-write helpers for viewer-driven plan writes (#286).
+
+Every viewer-driven write to a plan/spec doc is **frontmatter-only** by hard
+constraint. These helpers are the single, security-critical write path so the
+escape guard and the public-repo confirm gate aren't copy-pasted (and can't
+drift) across `plan-confirm`, `plan-ack`, and any future frontmatter writer.
+"""
+import json
+from pathlib import Path
+from typing import Optional
+
+from lib import frontmatter
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+
+def resolve_doc_path(repo_root: Path, rel: str) -> Optional[Path]:
+    """Absolute path of `rel` iff it is a real file inside repo_root, else None.
+
+    Guards the write surface: the resolved path must live under the repo root,
+    so a `../escape`, an absolute `rel`, or an in-repo symlink pointing outside
+    can't steer a frontmatter write at an arbitrary file."""
+    root = Path(repo_root).resolve()
+    try:
+        p = Path(repo_root) / rel
+        if not p.is_file():
+            return None
+        resolved = p.resolve()
+    except OSError:
+        return None
+    if resolved == root or root in resolved.parents:
+        return resolved
+    return None
+
+
+def public_repo_gate(slug, rel: str, cfg: dict, confirm, action: str) -> bool:
+    """Public-repo confirm-token gate (the viewer surfaces this as a modal).
+
+    Returns True when the write may proceed. When a gate is required and no valid
+    token was supplied, prints the `{needs_confirm, reason, token}` JSON the
+    viewer's executeWrite flow consumes and returns False — the caller must then
+    make NO write. `action` is the verb phrase spliced into the reason."""
+    if slug and needs_confirm(slug, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, slug, rel)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (f"{slug} is PUBLIC (or visibility unknown); {action} "
+                       f"a frontmatter write will be committed there."),
+            "token": make_token(slug, rel),
+        }))
+        return False
+    return True
+
+
+def set_key(doc_path: Path, key: str, value) -> bool:
+    """Set (`value` not None) or delete (`value` None) ONE frontmatter key,
+    preserving the body byte-for-byte. Returns True iff the file changed
+    (idempotent no-op → False), so callers can report "nothing to do"."""
+    meta, body = frontmatter.parse_file(doc_path)
+    if not isinstance(meta, dict):
+        meta = {}
+    if value is None:
+        if key not in meta:
+            return False
+        del meta[key]
+    else:
+        if meta.get(key) == value:
+            return False
+        meta[key] = value
+    frontmatter.write_file(doc_path, meta, body)
+    return True