@stylusnexus/work-plan 2026.6.11 → 2026.6.13

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

@@ -65,8 +65,17 @@ def run(args: list[str]) -> int:
 
 def _refresh_many(tracks: list, yes: bool) -> int:
     """Refresh one or more tracks. Computes proposed updates, then asks one
-    confirmation (or applies all if --yes)."""
+    confirmation (or applies all if --yes).
+
+    A track whose live fetch comes back incomplete (GitHub timeout, permission
+    error, or a frontmatter issue that no longer resolves) is SKIPPED, not
+    refreshed: the canonical table is rebuilt from frontmatter membership, so a
+    missing issue would render as '(not fetched)' and silently overwrite its
+    valid last-known row (#256). Skipped tracks are reported and force a nonzero
+    exit so `--yes` / `hygiene` callers can tell a degraded run from a clean one.
+    """
     pending = []
+    degraded = []  # (track, missing_nums) — fetch was incomplete; left untouched
     for i, track in enumerate(tracks, 1):
         print(f"  [{i}/{len(tracks)}] {track.path.name}...", flush=True)
         canonical = find_canonical_status_tables(track.body)
@@ -94,6 +103,22 @@ def _refresh_many(tracks: list, yes: bool) -> int:
         issues_by_num = {i["number"]: i for i in issues}
         state_by_num = {i["number"]: state_to_status_label(i.get("state")) for i in issues}
 
+        # Both render paths rebuild the table from frontmatter membership, so a
+        # frontmatter issue we couldn't fetch would land as a '(not fetched)'
+        # row, replacing its valid last-known values. Refuse to publish that:
+        # skip the track and surface the gap (#256). Table-only numbers that
+        # aren't in frontmatter don't feed the rebuild, so they don't gate.
+        unique_fm = set(frontmatter_nums)
+        missing = sorted(n for n in unique_fm if n not in issues_by_num)
+        if missing:
+            degraded.append((track, missing))
+            scope = ("no issues" if len(missing) == len(unique_fm)
+                     else f"{len(missing)}/{len(unique_fm)} issues")
+            nums = ", ".join(f"#{n}" for n in missing)
+            print(f"      ⚠ fetch returned {scope} short ({nums}) "
+                  f"— skipping to preserve current rows")
+            continue
+
         if canonical:
             # Canonical table → RE-DERIVE the whole block from frontmatter
             # membership + live data, milestone-ordered (#101). Re-deriving from
@@ -113,6 +138,9 @@ def _refresh_many(tracks: list, yes: bool) -> int:
         pending.append((track, new_body, detail))
 
     if not pending:
+        if degraded:
+            _report_degraded(degraded)
+            return 1
         print("All tracks in sync.")
         return 0
 
@@ -127,9 +155,29 @@ def _refresh_many(tracks: list, yes: bool) -> int:
     for track, new_body, _ in pending:
         write_file(track.path, track.meta, new_body)
     print(f"\n✓ Updated {len(pending)} file(s).")
+
+    if degraded:
+        _report_degraded(degraded)
+        return 1
     return 0
 
 
+def _report_degraded(degraded: list) -> None:
+    """Summarize tracks skipped because their live fetch was incomplete (#256).
+
+    Their tables are left exactly as they were — better a stale-but-valid row
+    than a '(not fetched)' placeholder published as truth. A persistently
+    missing number usually means the issue was deleted/transferred and should
+    be dropped from frontmatter."""
+    print(f"\n⚠ Skipped {len(degraded)} track(s) — live fetch was incomplete, "
+          f"so their tables were left untouched:")
+    for track, missing in degraded:
+        nums = ", ".join(f"#{n}" for n in missing)
+        print(f"    {track.path.name}: could not fetch {nums}")
+    print("  Re-run once GitHub is reachable, or drop deleted issues from "
+          "frontmatter (`/work-plan reconcile`).")
+
+
 def _rederive_canonical(track, canonical_tables, frontmatter_nums,
                         issues_by_num, state_by_num):
     """Rebuild the canonical block, milestone-ordered, from live data.

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/plan_worktree.py

@@ -0,0 +1,288 @@
+"""Resolve a repo's shared-tier (.work-plan/) directory, optionally via a
+worktree pinned to a dedicated plan branch (#260).
+
+A repo MAY pin its shared planning to its own `plan_branch` so planning churn
+never lands on code branches (dev/main/feature) or in PRs. When `plan_branch`
+is set, the shared tier is read/written through a git WORKTREE checked out at
+that branch, kept in a stable cache dir beside the work-plan config. When it's
+unset, the shared tier is simply the working tree's `.work-plan/` — the legacy
+behaviour, unchanged.
+
+Never raises — git absence/failure/timeout degrades to "no shared tier" (None),
+exactly like notes_vcs. A read must never break discovery.
+"""
+import hashlib
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from lib.config import DEFAULT_CONFIG_PATH
+
+GIT_TIMEOUT = 20
+
+# Worktrees live beside the config (so Claude ~/.claude and Codex ~/.agents both
+# work), keyed by a hash of the repo's local path so two repos never collide.
+_WORKTREE_ROOT = DEFAULT_CONFIG_PATH.parent / "plan-worktrees"
+
+
+def _git(cwd, *args, timeout: int = GIT_TIMEOUT):
+    """Run `git -C <cwd> <args>`; return CompletedProcess or None (never raises)."""
+    try:
+        return subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def _worktree_dir(local_path: Path) -> Path:
+    """Stable cache dir for this repo's plan worktree (keyed by its local path).
+
+    `resolve()` can touch the filesystem and raise OSError (symlink loop,
+    permissions) — fall back to the un-resolved absolute path so this never
+    raises and the never-raise contract holds upstream.
+    """
+    try:
+        resolved = str(local_path.resolve())
+    except OSError:
+        resolved = str(local_path.absolute())
+    key = hashlib.sha256(resolved.encode("utf-8")).hexdigest()[:16]
+    return _WORKTREE_ROOT / key
+
+
+def _ref_exists(local_path: Path, ref: str) -> bool:
+    proc = _git(local_path, "rev-parse", "--verify", "--quiet", ref)
+    return proc is not None and proc.returncode == 0
+
+
+def local_branch_exists(local_path: Path, branch: str) -> bool:
+    """True if `branch` exists as a local head. Never raises."""
+    return _ref_exists(Path(local_path).expanduser(), f"refs/heads/{branch}")
+
+
+def remote_branch_exists(local_path: Path, branch: str) -> bool:
+    """True if `origin/<branch>` exists in the local remote-tracking refs (may be
+    stale — fetch first for an authoritative answer). Never raises."""
+    return _ref_exists(Path(local_path).expanduser(),
+                       f"refs/remotes/origin/{branch}")
+
+
+def _branch_exists(local_path: Path, branch: str) -> bool:
+    """True if `branch` exists locally or as origin/<branch>."""
+    return (local_branch_exists(local_path, branch)
+            or remote_branch_exists(local_path, branch))
+
+
+def ensure_worktree(local_path: Path, branch: str) -> Optional[Path]:
+    """Ensure a worktree of `local_path` checked out at `branch` exists in the
+    cache; return its path, or None on any failure. Never raises.
+
+    Does NOT create the branch — if `branch` doesn't exist yet (bootstrap not
+    run), returns None so callers fall back to "no shared tier". Idempotent: an
+    already-present worktree is reused.
+    """
+    if not branch:
+        return None
+    local_path = Path(local_path).expanduser()
+    dest = _worktree_dir(local_path)
+    # A worktree's `.git` is a gitdir-pointer file (exists() catches file + dir).
+    if (dest / ".git").exists():
+        # Reuse ONLY if it's still checked out at `branch`. A worktree left on
+        # another branch (manual `git checkout`, or the branch was renamed)
+        # would otherwise get plan commits on the wrong branch — refuse and
+        # degrade to "no shared tier" rather than commit somewhere unexpected.
+        head = _git(dest, "rev-parse", "--abbrev-ref", "HEAD")
+        if head is not None and head.returncode == 0 and head.stdout.strip() == branch:
+            return dest
+        return None
+    if not _branch_exists(local_path, branch):
+        return None
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    proc = _git(local_path, "worktree", "add", "--quiet", str(dest), branch)
+    if proc is None or proc.returncode != 0:
+        return None
+    return dest
+
+
+def dirty_work_plan_paths(worktree: Path) -> list:
+    """Repo-relative paths under `.work-plan/` with uncommitted changes in the
+    worktree (staged, unstaged, or untracked). Empty list on any failure or a
+    clean tree. Never raises.
+
+    The dispatcher snapshots these BEFORE a command and commits only the paths
+    that appear AFTER — so a pre-existing dirty `.work-plan/` file from unrelated
+    manual edits is never swept into a plan commit triggered by an unrelated
+    subcommand.
+
+    Uses NUL-delimited porcelain (`-z`): unlike the line format, `-z` never
+    quote-wraps or octal-escapes paths, so filenames with spaces or non-ASCII
+    round-trip verbatim back into `git add` (the line format would wrap them in
+    quotes and break the commit). `-uall` enumerates untracked files
+    individually instead of collapsing a new dir to one `dir/` entry, so the
+    before/after delta is per-file. A staged rename's source path is captured
+    too, so the rename commits as a unit (dest add + source delete).
+    """
+    wt = Path(worktree).expanduser()
+    proc = _git(wt, "-c", "core.quotepath=false", "status", "--porcelain", "-z",
+                "--untracked-files=all", "--", ".work-plan")
+    if proc is None or proc.returncode != 0:
+        return []
+    fields = proc.stdout.split("\0")
+    paths = []
+    i, n = 0, len(fields)
+    while i < n:
+        entry = fields[i]
+        if len(entry) < 4:  # trailing empty field / malformed line
+            i += 1
+            continue
+        status, path = entry[:2], entry[3:]
+        if path:
+            paths.append(path)
+        # Rename/copy: porcelain -z follows the entry with the source path in
+        # the NEXT NUL field ("R  <dest>\0<source>"). Commit both so the rename
+        # lands atomically.
+        if "R" in status or "C" in status:
+            i += 1
+            if i < n and fields[i]:
+                paths.append(fields[i])
+        i += 1
+    return paths
+
+
+def commit_shared_tier(worktree: Path, message: str, paths) -> Optional[str]:
+    """Commit exactly `paths` (repo-relative, all under `.work-plan/`) in the
+    worktree with `message`; return the new short SHA, or None. Never raises.
+
+    Stages ONLY the explicit `paths` — not a blanket `.work-plan/` add — so a
+    `plan_branch` worktree never sweeps in code, other files, or pre-existing
+    dirty plan files the triggering command didn't touch. No-op when `paths` is
+    empty or nothing stages.
+
+    Commits on whatever branch the worktree is checked out — the caller has
+    already verified that's `plan_branch`. Local commit only; pushing the branch
+    (to actually share it) is a separate, deliberate step (#260, follow-up).
+    """
+    wt = Path(worktree).expanduser()
+    if not (wt / ".work-plan").is_dir():
+        return None
+    scoped = [p for p in (paths or []) if p]
+    if not scoped:
+        return None
+    if _git(wt, "add", "--", *scoped) is None:
+        return None
+    staged = _git(wt, "diff", "--cached", "--quiet", "--", *scoped)
+    if staged is None or staged.returncode == 0:
+        return None
+    proc = _git(wt, "commit", "-m", message, "--", *scoped)
+    if proc is None or proc.returncode != 0:
+        # Unstage what we just staged so a later, unrelated command doesn't
+        # commit this residue under its own message (the worktree index is
+        # durable across invocations). Working-tree content is preserved.
+        _git(wt, "reset", "--quiet", "--", *scoped)
+        return None
+    head = _git(wt, "rev-parse", "--short", "HEAD")
+    if head is None or head.returncode != 0:
+        return None
+    return head.stdout.strip() or None
+
+
+def shared_tier_dir(entry: dict) -> Optional[Path]:
+    """The `.work-plan/` directory to read/write for a repo config `entry`.
+
+    - `plan_branch` set  → the worktree's `.work-plan/` (None when the worktree
+      can't be ensured, e.g. the branch isn't bootstrapped yet).
+    - `plan_branch` unset → the working tree's `.work-plan/` (legacy, unchanged).
+
+    Returns None when the entry has no `local` path. Never raises.
+    """
+    if not entry or not entry.get("local"):
+        return None
+    local_path = Path(entry["local"]).expanduser()
+    branch = entry.get("plan_branch")
+    if branch:
+        worktree = ensure_worktree(local_path, branch)
+        return (worktree / ".work-plan") if worktree else None
+    return local_path / ".work-plan"
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 (#260): bootstrap + push. Creating an orphan plan branch, fetching a
+# teammate's, pushing local plan commits to share them. All never-raise.
+# ---------------------------------------------------------------------------
+
+def create_orphan_worktree(local_path: Path, branch: str) -> Optional[Path]:
+    """Create a worktree at the stable cache path holding a fresh ORPHAN
+    `branch` whose tree is an empty `.work-plan/` (no shared history with the
+    repo's code — like gh-pages). Returns the worktree path with `.work-plan/`
+    created but NOT yet committed (the caller seeds it and commits via
+    commit_shared_tier), or None on any failure. Never raises.
+
+    Caller must have verified `branch` does not already exist (local or remote);
+    this is the create path, not the connect path (use ensure_worktree to
+    connect to an existing branch).
+    """
+    local_path = Path(local_path).expanduser()
+    dest = _worktree_dir(local_path)
+    if (dest / ".git").exists():
+        return None  # a worktree is already cached here — caller should connect
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    # Detached worktree at HEAD, then orphan-checkout the plan branch and clear
+    # the code out of it so only .work-plan/ remains.
+    add = _git(local_path, "worktree", "add", "--detach", "--quiet", str(dest), "HEAD")
+    if add is None or add.returncode != 0:
+        return None
+    orphan = _git(dest, "checkout", "--orphan", branch)
+    if orphan is None or orphan.returncode != 0:
+        _git(local_path, "worktree", "remove", "--force", str(dest))
+        return None
+    # Drop every code file from the orphan's index + working tree.
+    if _git(dest, "rm", "-rf", "--quiet", ".") is None:
+        _git(local_path, "worktree", "remove", "--force", str(dest))
+        return None
+    try:
+        (dest / ".work-plan").mkdir(parents=True, exist_ok=True)
+    except OSError:
+        _git(local_path, "worktree", "remove", "--force", str(dest))
+        return None
+    return dest
+
+
+def fetch_branch(local_path: Path, branch: str) -> bool:
+    """Best-effort `git fetch origin <branch>` so remote_branch_exists is
+    authoritative (a teammate may have published the plan branch). True on
+    success, False on any failure/offline. Never raises — a read-only op."""
+    proc = _git(Path(local_path).expanduser(), "fetch", "--quiet", "origin", branch)
+    return proc is not None and proc.returncode == 0
+
+
+def is_published(local_path: Path, branch: str) -> bool:
+    """True if `branch` exists on origin (it's been shared). Never raises."""
+    return remote_branch_exists(local_path, branch)
+
+
+def unpushed_oneline(local_path: Path, branch: str) -> list:
+    """One-line summaries of commits on local `branch` not yet on origin
+    (`origin/<branch>..<branch>`). If origin/<branch> doesn't exist, every commit
+    on `branch` is unpushed. Empty list on any failure. Never raises."""
+    local_path = Path(local_path).expanduser()
+    rng = (f"origin/{branch}..{branch}"
+           if remote_branch_exists(local_path, branch) else branch)
+    proc = _git(local_path, "log", "--oneline", "--no-color", rng)
+    if proc is None or proc.returncode != 0:
+        return []
+    return [ln for ln in proc.stdout.splitlines() if ln.strip()]
+
+
+def push_plan_branch(local_path: Path, branch: str):
+    """Push `branch` to origin, setting upstream. Returns the CompletedProcess
+    (inspect .returncode / .stderr — the caller surfaces protected-branch and
+    other failures) or None if git couldn't run. Never raises."""
+    return _git(Path(local_path).expanduser(), "push", "--set-upstream",
+                "origin", branch, timeout=120)

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

@@ -10,6 +10,7 @@ from lib.config import (
     resolve_local_path_for_folder,
     is_valid_git_repo,
 )
+from lib.plan_worktree import shared_tier_dir
 from lib.git_state import parse_iso_timestamp
 
 _PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
@@ -210,8 +211,11 @@ def _discover_shared_tracks(cfg: dict, include_archive: bool = False,
         if not is_valid_git_repo(local_path):
             continue
         github_repo = entry.get("github")
-        notes_dir = local_path / ".work-plan"
-        if not notes_dir.is_dir():
+        # The shared tier is the working tree's .work-plan/ — UNLESS the repo
+        # pins a `plan_branch`, in which case it's read from a worktree checked
+        # out at that branch so planning never rides on code branches (#260).
+        notes_dir = shared_tier_dir(entry)
+        if notes_dir is None or not notes_dir.is_dir():
             continue
         for md_path in sorted(notes_dir.rglob("*.md")):
             # Skip dotfiles, README, and dash-led names (a `--repo.md` file

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"], [])