@stylusnexus/work-plan 2026.6.11 → 2026.6.13-2

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

@@ -17,12 +17,16 @@ _ORPHAN_RE = re.compile(
 
 
 def render_block(row: dict) -> str:
-    """Render the delimited status block from an evaluated row dict."""
+    """Render the delimited status block from an evaluated row dict.
+
+    A `verdict_override` (#286) appends a `✋ confirmed` marker so the banner
+    reads as a human-affirmed verdict, not a purely mechanical one."""
     last = row.get("last_touched") or "unknown"
+    confirmed = " · ✋ confirmed" if row.get("override") else ""
     line = (
         f"> **Status:** {row['glyph']} {row['verdict']} · "
         f"{row['files_present']}/{row['files_declared']} files · "
-        f"last touched {last}"
+        f"last touched {last}{confirmed}"
     )
     return f"{BEGIN}\n{line}\n{END}"
 

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_auth_status.py

@@ -0,0 +1,98 @@
+"""auth-status — gh auth probe (#auth). Offline: subprocess is mocked."""
+import io
+import json
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import auth_status
+from lib import github_state
+
+
+def _proc(returncode, stdout="", stderr=""):
+    return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+class GhAuthStatusHelperTest(unittest.TestCase):
+    def test_authenticated_parses_user(self):
+        out = _proc(0, stderr="✓ Logged in to github.com account evemcgivern (keyring)")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["authenticated"])
+        self.assertTrue(s["gh_present"])
+        self.assertEqual(s["user"], "evemcgivern")
+        self.assertIsNone(s["error"])
+
+    def test_authenticated_legacy_phrasing(self):
+        out = _proc(0, stderr="✓ Logged in to github.com as evemcgivern")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["authenticated"])
+        self.assertEqual(s["user"], "evemcgivern")
+
+    def test_not_logged_in(self):
+        out = _proc(1, stderr="You are not logged into any GitHub hosts. Run gh auth login")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertFalse(s["authenticated"])
+        self.assertTrue(s["gh_present"])      # gh ran, just not logged in
+        self.assertIsNone(s["user"])
+        self.assertIn("not logged", s["error"].lower())
+
+    def test_gh_not_installed(self):
+        with mock.patch("lib.github_state.subprocess.run", side_effect=FileNotFoundError()):
+            s = github_state.gh_auth_status()
+        self.assertFalse(s["gh_present"])
+        self.assertFalse(s["authenticated"])
+        self.assertIn("not found", s["error"].lower())
+
+    def test_timeout_is_present_but_unauthenticated(self):
+        with mock.patch("lib.github_state.subprocess.run",
+                        side_effect=subprocess.TimeoutExpired("gh", 30)):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["gh_present"])
+        self.assertFalse(s["authenticated"])
+
+
+class AuthStatusCommandTest(unittest.TestCase):
+    def _run(self, status, args):
+        with mock.patch("commands.auth_status.github_state.gh_auth_status", return_value=status):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = auth_status.run(args)
+        return rc, buf.getvalue()
+
+    def test_json_authenticated_exit_0(self):
+        status = {"gh_present": True, "authenticated": True, "user": "eve", "error": None}
+        rc, out = self._run(status, ["--json"])
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out), status)
+
+    def test_not_logged_in_exit_1(self):
+        status = {"gh_present": True, "authenticated": False, "user": None, "error": "x"}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 1)
+        self.assertIn("gh auth login", out)
+
+    def test_gh_missing_exit_2(self):
+        status = {"gh_present": False, "authenticated": False, "user": None, "error": "x"}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 2)
+        self.assertIn("not found", out.lower())
+
+    def test_human_authenticated_names_user(self):
+        status = {"gh_present": True, "authenticated": True, "user": "eve", "error": None}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 0)
+        self.assertIn("eve", out)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,121 @@
+"""close-issue (#305): the toolkit's only GitHub-mutating command. Offline —
+the gh subprocess is mocked."""
+import io
+import json
+import sys
+import unittest
+from contextlib import redirect_stdout, redirect_stderr
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import close_issue
+from lib import github_state
+
+
+def _proc(rc, stdout="", stderr=""):
+    return SimpleNamespace(returncode=rc, stdout=stdout, stderr=stderr)
+
+
+class CloseIssueHelperTest(unittest.TestCase):
+    def test_builds_gh_args_and_succeeds(self):
+        captured = {}
+        def fake_run(args, **kw):
+            captured["args"] = args
+            return _proc(0, stdout="✓ Closed issue #287")
+        with mock.patch("lib.github_state.subprocess.run", side_effect=fake_run):
+            ok, msg = github_state.close_issue("o/r", 287, reason="completed", comment="done")
+        self.assertTrue(ok)
+        self.assertEqual(
+            captured["args"],
+            ["gh", "issue", "close", "287", "--repo", "o/r",
+             "--reason", "completed", "--comment", "done"],
+        )
+
+    def test_omits_reason_and_comment_when_absent(self):
+        captured = {}
+        def fake_run(args, **kw):
+            captured["args"] = args
+            return _proc(0)
+        with mock.patch("lib.github_state.subprocess.run", side_effect=fake_run):
+            github_state.close_issue("o/r", 5)
+        self.assertEqual(captured["args"], ["gh", "issue", "close", "5", "--repo", "o/r"])
+
+    def test_invalid_repo_rejected(self):
+        ok, msg = github_state.close_issue("not-a-slug", 5)
+        self.assertFalse(ok)
+        self.assertIn("invalid repo", msg)
+
+    def test_gh_failure_surfaces_stderr(self):
+        with mock.patch("lib.github_state.subprocess.run",
+                        return_value=_proc(1, stderr="could not close: already closed")):
+            ok, msg = github_state.close_issue("o/r", 5)
+        self.assertFalse(ok)
+        self.assertIn("already closed", msg)
+
+    def test_never_raises_on_subprocess_error(self):
+        with mock.patch("lib.github_state.subprocess.run", side_effect=OSError("boom")):
+            ok, msg = github_state.close_issue("o/r", 5)
+        self.assertFalse(ok)
+
+
+class CloseIssueCommandTest(unittest.TestCase):
+    def _drive(self, args, slug_resolves="o/r", close_ret=(True, "✓ closed #5")):
+        with mock.patch("commands.close_issue.config_mod.load_config", return_value={"repos": {}}), \
+             mock.patch("commands.close_issue.config_mod.resolve_github_for_folder",
+                        return_value=slug_resolves), \
+             mock.patch("commands.close_issue.github_state.close_issue",
+                        return_value=close_ret) as mclose:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = close_issue.run(args)
+        return rc, out.getvalue(), err.getvalue(), mclose
+
+    def test_closes_with_slug(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--reason=completed", "--", "5"])
+        self.assertEqual(rc, 0)
+        mclose.assert_called_once_with("o/r", 5, reason="completed", comment=None)
+        self.assertIn("closed", out)
+
+    def test_resolves_key_to_slug(self):
+        rc, out, err, mclose = self._drive(["--repo=myrepo", "--", "9"], slug_resolves="org/myrepo")
+        self.assertEqual(rc, 0)
+        self.assertEqual(mclose.call_args[0][0], "org/myrepo")
+
+    def test_comment_passed_through(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--comment=done via dev", "--", "5"])
+        self.assertEqual(mclose.call_args[1]["comment"], "done via dev")
+        self.assertIn("with comment", out)
+
+    def test_invalid_reason_rejected(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--reason=bogus", "--", "5"])
+        self.assertEqual(rc, 2)
+        mclose.assert_not_called()
+
+    def test_non_integer_number_rejected(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--", "abc"])
+        self.assertEqual(rc, 2)
+        mclose.assert_not_called()
+
+    def test_gh_failure_returns_1(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--", "5"],
+                                           close_ret=(False, "no write access"))
+        self.assertEqual(rc, 1)
+        self.assertIn("no write access", err)
+
+    def test_unresolvable_repo_returns_1(self):
+        rc, out, err, mclose = self._drive(["--repo=ghost", "--", "5"], slug_resolves=None)
+        self.assertEqual(rc, 1)
+        mclose.assert_not_called()
+
+    def test_json_output(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--json", "--", "5"])
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out)["closed"], 5)
+
+
+if __name__ == "__main__":
+    unittest.main()

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."""
 
@@ -274,6 +290,31 @@ class GroupIssuesByMilestoneTest(unittest.TestCase):
         self.assertEqual(group_issues_by_milestone([]), [])
 
 
+class BuildExportPlanTest(unittest.TestCase):
+    """The track↔plan link badge on each Track (#285)."""
+
+    def test_plan_null_when_no_badge(self):
+        tracks = [_track("alpha", "o/r", [1])]
+        out = build_export(tracks, {"alpha": []}, {"o/r": "PRIVATE"}, now="t")
+        self.assertIsNone(out["tracks"][0]["plan"])
+
+    def test_plan_badge_passed_through(self):
+        tracks = [_track("alpha", "o/r", [1])]
+        badge = {"rel": "docs/plans/p.md", "resolved": True, "verdict": "shipped",
+                 "glyph": "✅", "files_present": 9, "files_declared": 9,
+                 "checkboxes_done": 0, "checkboxes_total": 24, "lie_gap": False,
+                 "stalled": False, "override": "shipped"}
+        out = build_export(tracks, {"alpha": []}, {"o/r": "PRIVATE"}, now="t",
+                           plan_by_track={"alpha": badge})
+        self.assertEqual(out["tracks"][0]["plan"], badge)
+
+    def test_unresolved_badge_passed_through(self):
+        tracks = [_track("alpha", "o/r", [1])]
+        out = build_export(tracks, {"alpha": []}, {"o/r": "PRIVATE"}, now="t",
+                           plan_by_track={"alpha": {"rel": "docs/plans/p.md", "resolved": False}})
+        self.assertEqual(out["tracks"][0]["plan"], {"rel": "docs/plans/p.md", "resolved": False})
+
+
 class BuildExportDependsOnTest(unittest.TestCase):
     """Tests that depends_on is surfaced in the export JSON (#102)."""
 
@@ -292,3 +333,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"], [])