@stylusnexus/work-plan 2026.6.11 → 2026.6.13

package/README.md

@@ -138,6 +138,22 @@ The CLI never auto-pushes. When you create or update a shared track, it prints a
 ↑ shared — commit + push to share with teammates.
 ```
 
+### Canonical plan branch (`plan-branch`)
+
+Storing the plan as files *in* the repo makes it branch-scoped — but a track's status and priorities are facts about the **project**, not about a code branch. On a repo with `dev` + `main` + feature branches that means cross-branch plan divergence, merge conflicts on status-table edits, and planning churn polluting feature PRs and the deploy diff.
+
+`plan-branch` pins the shared tier to **one canonical branch** per repo, read and written through a dedicated git worktree, so the plan lives off your code branches entirely — yet the CLI and VS Code viewer always show it from any checkout.
+
+```bash
+/work-plan plan-branch init myproject        # orphan branch `work-plan/plan` + skeleton (local only)
+/work-plan plan-branch status myproject      # exists? published? how many unpushed commits?
+/work-plan plan-branch push myproject        # share it — gated with a confirm token on PUBLIC repos
+```
+
+The default branch is an **orphan** `work-plan/plan` (no shared history with your code, like `gh-pages`) — override with `--branch=<name>`. `init` is **local only**; a teammate who already published the branch is auto-**connected** instead of re-created. Once `plan_branch` is set, every shared-track write is committed onto that branch via the worktree (never your working branch), and `push` is the one deliberate step that shares it. `push --dry-run` previews exactly what would be exposed first.
+
+> **Tip:** exclude the plan branch from CI by adding `!work-plan/**` to your workflow's `on: push` branch filter, so planning commits never trigger builds or deploys.
+
 **Opt out per-command:** pass `--private` to route a specific track to `notes_root` instead:
 
 ```bash
@@ -281,7 +297,7 @@ To install for **both** Claude Code AND Codex, run the installer twice with diff
 
 ### VS Code extension
 
-The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph (with focus toggle and repo-scoped full map), the Untracked bucket, cross-track dependency chips, per-issue move buttons, and full read/write (slot/close/edit/move/new-track/…) with a public-repo confirm modal.
+The **Work Plan** extension is the visual face of the CLI — a sidebar tree (repos → tracks), a Mermaid dependency graph (with focus toggle and repo-scoped full map), the Untracked bucket, cross-track dependency chips, per-issue move buttons, **keyword issue search** (`%wildcard%` substitution, results in a dedicated tab), the daily-driver **Brief / Re-orient / Handoff** commands, an inline **active lens + sort** indicator under the view title, and full read/write (slot/close/edit/move/new-track/…) with a public-repo confirm modal.
 
 ![Work Plan VS Code extension — sidebar and dependency graph](https://raw.githubusercontent.com/stylusnexus/work-plan-toolkit/main/vscode/media/screenshots/dependency-graph.png)
 
@@ -495,15 +511,17 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `orient [track]` (alias: `where-was-i`) | Read-only paste block. With a track name: ~15-line track summary (priority, last session, next pick, git state). With no track: cwd snapshot (branch, recent commits, modified files) for non-track work. Add `--pick` for the interactive track picker. |
 | `slot <issue-num> [track]` | A new GitHub issue should belong to a track — adds it to the track's `github.issues` list. Non-interactive flags: `--move`/`--no-move` (relocate the issue off its prior track, or leave it; default no-move), `--confirm=<token>` (public-repo gate, see below). |
 | `close <track> [--state=shipped\|parked\|abandoned] [--note=<text>]` | Mark track shipped, parked, or abandoned. Moves to `archive/<state>/` for shipped/abandoned. Pass `--state=` (and an optional `--note=`) to run without prompts. |
-| `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Sync issue STATE (open/closed, status labels) from GitHub into the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." For a **canonical** table it re-derives the whole block from live data, milestone-ordered (active milestone first; see `canonicalize`), so the table self-heals and stays grouped instead of decaying; narrative (non-canonical) tables are updated conservatively in place. `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
+| `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Sync issue STATE (open/closed, status labels) from GitHub into the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." For a **canonical** table it re-derives the whole block from live data, milestone-ordered (active milestone first; see `canonicalize`), so the table self-heals and stays grouped instead of decaying; narrative (non-canonical) tables are updated conservatively in place. If the live fetch comes back incomplete (GitHub timeout/permission error, or a frontmatter issue that no longer resolves), that track is **skipped and left untouched** rather than rewriting valid rows as `(not fetched)`, and the command exits nonzero so sweeps can flag the degraded run. `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
 | `hygiene [--repo=<key>]` | Weekly all-in-one: `refresh-md` + `reconcile` + `duplicates`. With `--repo=<key>`, steps 1 and 2 scope to that repo and the global `duplicates` step is skipped. |
 | `list [--all] [--sort=recent\|priority]` | List active tracks (or all including parked/archived). `--sort=recent` orders by `last_touched` (most recent first); `--sort=priority` orders by `launch_priority` (P0→P3) with recency as tiebreaker. Default keeps discovery order. |
 | `init <path> [--priority=P0..P3] [--milestone=<m>]` | Add frontmatter to a brand-new track .md file (the file must already exist). Pass `--priority=`/`--milestone=` to skip the prompts. |
-| `init-repo <key> --github=<slug> [--local=<path>]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. `--github` is required; `--local` is optional. |
+| `init-repo <key> --github=<slug> [--local=<path>] [--update [--clear-local]]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. `--github` is required for an add; `--local` is optional. `--update` on an existing key changes its local/github; `--update --clear-local` forgets the saved local path (keeps github + other fields). `--clear-local` and `--local` are mutually exclusive. |
+| `remove-repo <key>` | Unregister a repo: delete its block from your config. **Config-only** — the notes folder, any tracks, and the local clone are left untouched (a notes folder or tracks that referenced it are now orphaned and can be removed by hand). Completes the add/update/remove trio with `init-repo`. |
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `rename-track <old-slug \| old@repo> <new-slug> [--repo=<key>] [--fix-refs] [--commit]` | Rename an active track's slug: moves its `.md` file and updates the frontmatter `track` field + `last_touched`. Validates `<new-slug>` like `new-track` and rejects a name already taken in the same repo/tier. For shared tracks, `--commit` stages + commits the move (otherwise it prints a "commit to share" hint). `--fix-refs` rewrites sibling tracks' `depends_on` that reference the old slug; without it they're just warned about. Archived tracks are immutable. Public-repo gated. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
 | `notes-vcs <init\|enable\|disable\|status\|undo> [<sha>] [--no-enable] [--json]` | Opt-in **local** version control for the private `notes_root` tier — history/undo for tracks on your machine, never pushed. `init` git-inits `notes_root` as a personal repo (baseline commit of existing tracks) and turns on auto-commit (`--no-enable` skips that). For safety it **refuses** a `notes_root` that already has a git remote or is a repo work-plan didn't create. When on, every track-mutating command (`slot`/`group`/`handoff`/`close`/`set`/…) commits **only the files it changed** (pre-existing uncommitted edits are left alone) as an undoable commit. The shared tier is unaffected — it's versioned by its own repo. `status` shows whether `notes_root` is a repo, whether auto-commit is on, and the last commit (`--json` for the machine shape the VS Code viewer polls). `undo [<sha>]` reverts a commit (default HEAD) — reverses the last edit. |
+| `plan-branch <init\|status\|push> <repo> [--branch=<name>] [--confirm=<token>] [--dry-run] [--json]` | Set up and share a repo's canonical **shared-tier** plan branch. The `.work-plan/` tier is pinned to ONE per-repo `plan_branch`, read/written through a dedicated git worktree, so planning never diverges across code branches or pollutes PR / deploy diffs. `init` creates that branch + a `.work-plan/` skeleton (default an **orphan** `work-plan/plan` — zero shared history with code, like `gh-pages`; override with `--branch`) and records `plan_branch` in config — or **connects** to a teammate's already-published branch if one exists. `init` is **local only** (no push). `status` reports whether the branch exists, is published to origin, and how many commits are unpushed (`--json` for the machine shape). `push` shares it: on a **public** repo it prints a confirm heads-up + token and exits (re-run with `--confirm=<token>`); `--dry-run` previews the commits that would push. Requires a repo registered via `init-repo` with a local clone path. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
 | `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
 | `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
@@ -521,7 +539,11 @@ Every write verb the VS Code extension drives runs **without a TTY** — explici
 
 `needs_confirm` fails **closed** — unknown visibility prompts too. An all-private team can opt out of the *unknown-visibility* case (e.g. when a `gh` lookup flakes) by setting `assume_private_when_unknown: true` in `~/.claude/work-plan/config.yml`; **public repos always prompt regardless.**
 
-`export --json` is the viewer's read surface (schema 1): every frontmatter'd track plus an additive `untracked` list of open issues that no track references, per repo.
+`export --json` is the viewer's read surface (schema 1): every frontmatter'd track plus an additive `untracked` list of open issues that no track references, per repo. It also emits a top-level `repos` list — every configured repo (`folder`/`repo`/`local`/`has_local`/`visibility`), tracked or not — so the viewer can show a freshly registered repo in the sidebar independent of whether it has any tracks yet.
+
+`list-open-issues --repo=<owner/name> [--exclude=<csv>]` is a second viewer read surface: it emits a repo's **open** issues as JSON (`{repo, issues:[…]}`, the same per-issue shape as `export`). The extension's **Slot** command uses it to offer a pick-list instead of a typed number; `--exclude` drops the track's current issues so they don't reappear. Unlike `export`'s `untracked` (open issues in *no* track), this includes issues tracked by *other* tracks — they're valid slot targets. Read-only.
+
+`plan-status --json` is the viewer's **Plans view** read surface: alongside each doc's verdict it now also emits `manifest_last_touched` (the most recent commit date across the plan's declared files), `stalled`, `lie_gap`, `unchecked_items`, and `stall_days`. The staleness window honors `stall_days:` in `~/.claude/work-plan/config.yml` and a `--stall-days=<n>` flag (precedence: flag → config → default 14). The viewer consumes these to flag plans whose declared-file build has gone cold — a `partial` plan with no recent commit on its manifest ("stalled") — and plans scored shipped whose own phase checkboxes are mostly unticked ("lie-gap").
 
 ## Version
 

package/VERSION

@@ -1 +1 @@
-2026.06.11+8c21445
+2026.06.13+627d944

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.11",
+  "version": "2026.6.13",
   "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"

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

@@ -1,7 +1,7 @@
 """export subcommand — emit the viewer-ready JSON read surface."""
 import json
 from datetime import datetime
-from lib.config import load_config, ConfigError
+from lib.config import load_config, ConfigError, resolve_local_path_for_folder
 from lib.tracks import discover_tracks
 from lib.github_state import fetch_export_issues, fetch_open_issues, repo_visibility
 from lib.export_model import build_export
@@ -60,10 +60,28 @@ def run(args: list[str]) -> int:
         open_rows = fetch_open_issues(repo)
         untracked_by_repo[repo] = [r for r in open_rows if r.get("number") not in tracked]
 
+    # Every CONFIGURED repo, regardless of whether any track references it (#288).
+    # Lets the viewer show a registered-but-empty repo so the user can start
+    # adding tracks to it. visibility is filled here for repos no track covered.
+    config_repos = []
+    for folder, block in (cfg.get("repos") or {}).items():
+        slug = block.get("github") if isinstance(block, dict) else None
+        local = resolve_local_path_for_folder(folder, cfg)
+        if slug and slug not in visibility:
+            visibility[slug] = repo_visibility(slug)
+        config_repos.append({
+            "folder": folder,
+            "repo": slug,
+            "local": str(local) if local else None,
+            "has_local": bool(local and local.exists()),
+            "visibility": visibility.get(slug),
+        })
+
     now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
     print(json.dumps(
         build_export(tracks, issues_by_track, visibility, now,
-                     untracked_by_repo=untracked_by_repo),
+                     untracked_by_repo=untracked_by_repo,
+                     config_repos=config_repos),
         indent=2,
     ))
     return 0

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

@@ -15,6 +15,7 @@ from datetime import datetime
 from pathlib import Path
 
 from lib.config import load_config, ConfigError, is_valid_git_repo
+from lib.plan_worktree import shared_tier_dir
 from lib.frontmatter import parse_file, write_file
 from lib.notes_readme import seed_readme
 from lib.scratch import cache_dir
@@ -182,7 +183,10 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
     if not use_private and local_raw:
         local_path = Path(local_raw).expanduser()
         if is_valid_git_repo(local_path):
-            shared_dir = local_path / ".work-plan"
+            # Worktree-aware (#260): for a `plan_branch` repo this resolves to
+            # the worktree's .work-plan/; otherwise the working tree's. None when
+            # a plan_branch isn't bootstrapped yet → falls back to private tier.
+            shared_dir = shared_tier_dir(repo_entry)
 
     if shared_dir is not None:
         track_dir = shared_dir

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

@@ -50,10 +50,56 @@ def _report_shared_tracks(local_path: "Path | None") -> None:
         )
 
 
+def _update_existing(key: str, github: str, local: "str | None", clear_local: bool = False) -> int:
+    """Update an already-registered repo's local (and github if it differs).
+
+    Does NOT recreate the notes folder / archive dirs — they already exist.
+    Uses the same env()-via-opaque-block yq pattern as a fresh add, setting only
+    the fields that change so other keys in the block are preserved.
+
+    clear_local sets `.repos.<key>.local = null` (forget a stale checkout path)
+    while keeping github + every other field. Mutually exclusive with `local`
+    (enforced in run() before this is called).
+    """
+    updates = {}
+    if clear_local:
+        # JSON null → YAML null; the * merge overwrites local with null, leaving
+        # github + other keys intact (same opaque-env discipline as below).
+        updates["local"] = None
+    elif local:
+        updates["local"] = local
+    if github:
+        updates["github"] = github
+    if not updates:
+        print(f"ℹ Nothing to update for repo '{key}' (no --local, --clear-local, or --github given).")
+        return 0
+
+    # `key` is validated against ^[a-z][a-z0-9-]*$ in run() before this is called,
+    # so it's safe in the yq path. Field values travel as an OPAQUE env value via
+    # env() (parsed as JSON), never interpolated — uniform with the add path.
+    env = {**os.environ, "WP_REPO_UPDATES": json.dumps(updates)}
+    yq_expr = f".repos.{key} = (.repos.{key} // {{}}) * env(WP_REPO_UPDATES)"
+    try:
+        subprocess.run(
+            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True, env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return 1
+    if clear_local:
+        print(f"✓ Cleared local path for '{key}'")
+    elif local:
+        print(f"✓ Updated repo '{key}' local path → {local}")
+    else:
+        print(f"✓ Updated repo '{key}' in {DEFAULT_CONFIG_PATH}")
+    return 0
+
+
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--github", "--local"})
+    flags, positional = parse_flags(args, {"--github", "--local", "--update", "--clear-local"})
     if not positional:
-        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>]")
+        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>] [--update [--clear-local]]")
         return 2
 
     key = positional[0]
@@ -61,13 +107,23 @@ def run(args: list[str]) -> int:
         print(f"ERROR: '{key}' is not a valid key. Use lowercase letters, digits, hyphens; must start with a letter.")
         return 2
 
-    # --github is required; no prompt fallback
+    clear_local = bool(flags.get("--clear-local"))
+    local = flags.get("--local") or None
+
+    # --clear-local forgets the saved local path; pairing it with --local (which
+    # SETS a path) is contradictory.
+    if clear_local and local:
+        print("ERROR: --clear-local and --local are mutually exclusive.")
+        return 2
+
+    # --github is required for a fresh add / a github change, but --clear-local is
+    # a field-only edit on an existing block, so we don't force it there.
     github = flags.get("--github")
-    if not github or "/" not in github:
-        if not github:
-            print("ERROR: --github is required (e.g. --github=org/repo).")
-        else:
-            print("ERROR: github slug must be in the form 'org/repo'.")
+    if github and "/" not in github:
+        print("ERROR: github slug must be in the form 'org/repo'.")
+        return 2
+    if not github and not clear_local:
+        print("ERROR: --github is required (e.g. --github=org/repo).")
         return 2
 
     try:
@@ -77,19 +133,33 @@ def run(args: list[str]) -> int:
         print("\nRun ./install.sh from the toolkit root to seed your config first.")
         return 1
 
-    if key in cfg.get("repos", {}):
-        print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
-        print("Edit it manually, or pick a different key.")
-        return 1
+    update = bool(flags.get("--update"))
+    existing = cfg.get("repos", {})
 
-    # --local is optional; if absent, skip (no prompt)
-    local = flags.get("--local") or None
+    # --clear-local is an update-only operation on an existing key.
+    if clear_local:
+        if not update:
+            print("ERROR: --clear-local requires --update (it edits an existing repo).")
+            return 2
+        if key not in existing:
+            print(f"ERROR: repo '{key}' not found in {DEFAULT_CONFIG_PATH} — nothing to clear.")
+            return 1
+        return _update_existing(key, github or "", None, clear_local=True)
+
+    # --local is optional; if absent, skip (no prompt). Validate it exists.
     local_path = None
     if local:
         local_path = Path(local).expanduser()
         if not local_path.exists():
             print(f"WARN: {local_path} does not exist. Saving anyway — fix later if wrong.")
 
+    if key in existing:
+        if not update:
+            print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
+            print("Pass --update to change its local path, or pick a different key.")
+            return 1
+        return _update_existing(key, github, local)
+
     notes_root = Path(cfg["notes_root"]).expanduser()
     if not notes_root.exists():
         print(f"ERROR: notes_root {notes_root} does not exist.")

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

@@ -0,0 +1,52 @@
+"""list-open-issues subcommand — emit a repo's open issues as JSON.
+
+A read surface for the VS Code viewer's Slot command (#282): Slot adds an issue
+that is typically NOT already in the track, so the per-track export can't supply
+the candidate list. This fetches the repo's open issues live via `gh` and emits
+them in the same `Issue` shape the export uses, so the viewer can offer a
+pick-list instead of a free-typed number.
+
+Read-only. Never writes anything. The viewer passes the track's current issue
+numbers via --exclude so already-slotted issues are filtered out here.
+"""
+import json
+
+from lib.github_state import fetch_open_issues
+from lib.export_model import normalize_issue
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--repo", "--exclude"})
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print(json.dumps({"error": "list-open-issues requires --repo=<owner/name>"}))
+        return 2
+
+    exclude = _parse_exclude(flags.get("--exclude"))
+
+    # fetch_open_issues validates the slug and returns [] on any error/bad repo,
+    # so a malformed --repo yields an empty list rather than raising.
+    rows = fetch_open_issues(repo)
+    issues = [
+        normalize_issue(r) for r in rows
+        if r.get("number") not in exclude
+    ]
+    print(json.dumps({"repo": repo, "issues": issues}, indent=2))
+    return 0
+
+
+def _parse_exclude(raw) -> set:
+    """Parse the --exclude CSV (e.g. "87,91,103") into a set of ints.
+
+    Tolerates blanks and non-numeric tokens (skipped), so a stray trailing
+    comma or empty value never errors. `True` (bare --exclude) → empty set."""
+    if not raw or raw is True:
+        return set()
+    out = set()
+    for tok in str(raw).split(","):
+        tok = tok.strip()
+        if tok.isdigit():
+            out.add(int(tok))
+    return out

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

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import Optional
 
 from lib.config import load_config, ConfigError, is_valid_git_repo
+from lib.plan_worktree import shared_tier_dir
 from lib.frontmatter import write_file
 from lib.prompts import parse_flags
 from lib.write_guard import needs_confirm, make_token, valid_token
@@ -150,11 +151,16 @@ def run(args: list[str]) -> int:
 
     shared_path: Optional[Path] = None
     if not use_private and folder in cfg.get("repos", {}):
-        local_raw = cfg["repos"][folder].get("local")
+        repo_entry = cfg["repos"][folder]
+        local_raw = repo_entry.get("local")
         if local_raw:
             local_path = Path(local_raw).expanduser()
             if is_valid_git_repo(local_path):
-                shared_path = local_path / ".work-plan" / f"{slug}.md"
+                # Worktree-aware (#260): plan_branch repos write into the
+                # worktree's .work-plan/; None → fall back to the private tier.
+                sd = shared_tier_dir(repo_entry)
+                if sd is not None:
+                    shared_path = sd / f"{slug}.md"
 
     notes_root = Path(cfg["notes_root"]).expanduser()
     if shared_path is not None: