@stylusnexus/work-plan 2026.6.11 → 2026.6.13-2

package/README.md

@@ -111,7 +111,7 @@ flowchart TB
 
 > **When should I run `refresh-md`?** Any time you close or merge issues and want the track body to reflect the new state. `handoff` rewrites the status table for one track on every run, but `brief` reads GitHub live without writing anything back — so a track you haven't `handoff`'d recently stays stale on disk. `refresh-md <track>` (or **Sync Issue States from GitHub** in VS Code) fixes that on-demand; `hygiene` sweeps all tracks weekly.
 
-> **GitHub access is read-only.** The toolkit never writes to GitHub. All issue data comes from read-only `gh` CLI calls (`gh issue list`, `gh issue view`). Every write (frontmatter, status table, session log) goes to your local markdown files only.
+> **GitHub access is read-only by default, with two explicit, opt-in write actions.** Issue *data* always comes from read-only `gh` calls (`gh issue list`, `gh issue view`), and every routine write (frontmatter, status table, session log) goes to your local markdown files only. The two GitHub-*mutating* actions are both opt-in and gated: `plan-status --issues` **creates** a GitHub issue per partial plan (`gh issue create`, prompts before opening), and `close-issue` (#305) **closes** an issue via `gh issue close` — for the common case where a PR merged to `dev` left its issue OPEN (GitHub auto-closes only from the default branch), with the VS Code viewer firing a mandatory "Close on GitHub? — cannot be undone" modal on every close. Nothing else touches GitHub state.
 
 ## Shared tracks
 
@@ -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, with per-track open/closed counts and an **activity-bar badge** for blocked/open status), a Mermaid dependency graph (with focus toggle and repo-scoped full map), per-track detail with an **open/closed progress bar** and a one-click **Plan** link, the Untracked bucket, cross-track dependency chips, per-issue move/close 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, a **Plans view** with confirm-gated frontmatter writes (verdict / acknowledge / drift-baseline) and a fast-fail GitHub-auth banner, and full read/write (slot/close/edit/move/new-track/push-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)
 
@@ -474,7 +490,7 @@ The bundled `notes/` folder stays empty until you run `/work-plan init-repo <key
 ## Security & data handling
 
 - **No credentials stored.** All GitHub access goes through your existing `gh auth`. This toolkit never reads, writes, or stores GitHub tokens.
-- **Local-only writes.** The skill writes to `~/.claude/skills/work-plan/`, `~/.claude/skills/repo-activity-summary/`, `~/.claude/commands/work-plan.md`, `~/.claude/work-plan/config.yml`, and your `notes_root`. The exceptions are the `plan-status` action flags, all confined to the repo you point it at and all opt-in: `--stamp` writes a status header into discovered plan docs; `--archive` `git mv`s dead plans into `archive/abandoned/`; `--issues` opens GitHub issues for partial plans (via `gh`). All honor `--draft` (preview, no writes) and the two mutating actions prompt for confirmation. Nothing else.
+- **Writes are local by default; every remote/GitHub write is opt-in and gated.** The skill writes to `~/.claude/skills/work-plan/`, `~/.claude/skills/repo-activity-summary/`, `~/.claude/commands/work-plan.md`, `~/.claude/work-plan/config.yml`, and your `notes_root`. Repo-confined writes: the `plan-status` action flags (`--stamp` writes a status header into discovered plan docs; `--archive` `git mv`s dead plans into `archive/abandoned/`; all honor `--draft` and prompt), and the frontmatter-only plan writers `plan-confirm` (`verdict_override`), `plan-ack` (`acknowledged`), `plan-baseline` (`verdict_baseline`) — each writes one key into a plan doc's **YAML frontmatter only** (never its body/checkboxes/manifest), public-repo gated. **GitHub-mutating** (opt-in, gated): `plan-status --issues` *creates* an issue per partial plan, and `close-issue` *closes* an issue (`gh issue close`). **Remote git push** (opt-in, public-repo gated): `plan-branch push` and `push-track` publish the shared plan branch. Nothing else.
 - **No telemetry, no network calls beyond `gh`.** All GitHub operations go through `gh` (your authenticated session); no direct HTTP requests are made.
 - **AI subcommands (`group`, `suggest-priorities`) send issue titles to Claude** via Claude Code's existing integration. Body content, code, and PR contents are NOT sent. If your repo is private and you're cautious about what reaches the model, skip these subcommands.
 - **`init-repo` writes to your config via `yq -i`.** Inputs are JSON-encoded before being passed to `yq`, so a maliciously crafted `--github=` value can't break out of the YAML edit.
@@ -495,15 +511,18 @@ 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. |
+| `push-track <track\|track@repo> [--repo=<key>] [--no-push] [--confirm=<token>]` | **Promote a private track to the shared tier and publish it** (#306). Moves the track's `.md` from `notes_root` into the repo's `.work-plan/` (on its `plan_branch`, via a worktree), removes the private copy so it isn't duplicated, commits to the plan branch, and pushes — unless `--no-push`. Tier is derived from location, so this is a file move, not a frontmatter edit. Requires a local clone + a configured `plan_branch` (else hints `plan-branch init`). Pushing to a **public** repo makes the track world-visible → confirm-token gated. |
+| `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). |
@@ -512,6 +531,9 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
 | `canonicalize <track>` | Add a canonical issue table to a track file (so `refresh-md` knows where to update). The table carries a `Milestone` column and is ordered active-milestone-first — issues in the track's `milestone_alignment` milestone, then other milestones grouped (blank divider row between groups), then no-milestone last — so "what's next" sits above "someday" (#101). It's one table (not per-milestone sub-tables) so `refresh-md` re-derives it cleanly. |
 | `plan-status [--repo=<key>] [--json] [--stamp [--draft]] [--llm [--apply]] [--archive \| --issues] [--draft]` | Reach a verdict on every plan/spec doc in a repo by correlating its declared file-manifest against git + the filesystem: ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less / 🧳 foreign. Read-only by default. `--stamp` writes an idempotent status header into each doc (`--draft` previews); `--llm` runs a two-step AI verdict on prose/ambiguous docs; `--archive` moves dead plans to `archive/abandoned/` and `--issues` opens issues for partial plans (both gated, both honor `--draft`); `--json` for machine output. |
+| `plan-confirm --repo=<key> --verdict=shipped\|partial\|dead [--clear] [--confirm=<token>] -- <rel>` | Affirm a **human** verdict on ONE plan/spec doc by writing `verdict_override` into its YAML **frontmatter only** (never the body, checkboxes, manifest, or status banner). `plan-status` then pins that verdict over the mechanical one and silences the "shipped but boxes unchecked" lie-gap. Use when a genuinely-shipped plan is flagged only because its phase checkboxes were never ticked. `<rel>` is the repo-relative doc path. Public-repo gated (`--confirm=<token>`); `--clear` removes the override. |
+| `plan-ack --repo=<key> [--clear] [--confirm=<token>] -- <rel>` | Persist a **durable acknowledgment** into ONE plan/spec doc's YAML **frontmatter only** (`acknowledged: true`) — a "stop flagging this" that's committed with the repo and shared with teammates, unlike the VS Code viewer's per-machine `workspaceState` ack. `plan-status` reads it back (emits `acknowledged`) and demotes the doc. `<rel>` is the repo-relative doc path. Public-repo gated (`--confirm=<token>`); `--clear` removes it. |
+| `plan-baseline --repo=<key> [--clear] [--confirm=<token>] -- <rel>` | Stamp the **current computed verdict** into ONE plan/spec doc's YAML **frontmatter only** (`verdict_baseline`) as a drift tripwire. `plan-status` then flags **drift** (emits `verdict_drift`) when the live verdict later diverges from the baseline — catching a once-shipped plan that silently **regressed** (its declared files were deleted/moved), the third "started, then drifted off" signal beyond stalled + lie-gap. The value is computed authoritatively (not taken from the caller); a human `verdict_override` suppresses drift. Public-repo gated; `--clear` removes it. |
 
 Run `python3 ~/.claude/skills/work-plan/work_plan.py --help` for the full list with examples.
 
@@ -521,7 +543,17 @@ 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.
+
+**Track ↔ plan link (#285).** A track can name its plan/spec doc with a `plan: <repo-relative-path>` field in its frontmatter — set it with `set <track> plan=docs/superpowers/plans/<file>.md` (empty `plan=` clears it; a path that doesn't resolve in the repo checkout is saved with an advisory warning). `export --json` then resolves that link into a per-track `plan` object — `{rel, resolved, verdict, glyph, files_present/declared, checkboxes_done/total, lie_gap, stalled, override}` — computed by the **same evaluator `plan-status` uses**, so the badge never disagrees with the Plans view. An unresolvable link (no local clone, or the file is absent) emits `{rel, resolved:false}`. Only the *declared* link is trusted — there is no filename-to-slug guessing (which false-matches and misses). The viewer surfaces this as a one-click **Plan** affordance on the track detail panel.
+
+`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.
+
+`auth-status [--json]` is the viewer's **auth probe**: it runs `gh auth status` and emits `{gh_present, authenticated, user, error}` (exit `0` authenticated / `1` gh present but not signed in / `2` gh not found). Because every GitHub read goes through `gh` and the fetch helpers return empty rather than erroring, an unauthenticated session would otherwise look like an empty-but-working one. The extension calls this at activation (and after every refresh) to **fast-fail with a clear "Not signed in to GitHub" banner + a Sign in path** instead of rendering a misleadingly empty tree — and distinguishes "not signed in" (`gh auth login`) from "gh not installed" (a different fix). 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"). It also emits `override` (the human `verdict_override`, `shipped`/`partial`/`dead` or `null`, set via `plan-confirm` — when present the CLI pins the verdict to it and forces `lie_gap` false), `acknowledged` (the durable frontmatter ack set via `plan-ack`), and `verdict_baseline` + `verdict_drift` (the drift tripwire set via `plan-baseline` — `verdict_drift` is true when the live verdict no longer matches the stamped baseline, suppressed under an override). It also emits `offtree_paths`: declared manifest paths that resolve **outside** the repo (absolute, `~`, `..`-escape, junk `/`) — a read-only flag for a typo or misfiled plan that would otherwise silently drag the file score down (the 🧳 foreign verdict only fires when *most* paths are off-tree; this surfaces the sub-threshold ones too). Never auto-fixed — surfacing only.
+
+**The Plans view can write to plan-doc frontmatter — and only frontmatter.** Right-click a plan in the viewer → **Confirm Verdict…** / **Clear Confirmation** (writes `verdict_override`), **Acknowledge & Save to Doc** / **Clear Saved Acknowledgment** (writes `acknowledged`), or **Stamp Baseline — Watch for Drift** / **Clear Baseline** (writes `verdict_baseline`) drives the matching CLI write behind a mandatory modal that names the exact file and states the write touches only the doc's YAML frontmatter — never its prose body, checkboxes, or declared-file manifest. These are the only viewer-initiated writes to a plan doc, each touches one frontmatter key and nothing else, and on a public repo each additionally passes through the public-repo confirm modal above. The default **Acknowledge (stop flagging)** remains per-machine and writes nothing to git; **Acknowledge & Save to Doc** is the opt-in durable, shared variant. Everything else the Plans view does (scan, local acknowledge) remains read-only on git.
 
 ## Version
 

package/VERSION

@@ -1 +1 @@
-2026.06.11+8c21445
+2026.06.13+22f59a8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.11",
+  "version": "2026.6.13-2",
   "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/SKILL.md

@@ -29,6 +29,9 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan reconcile <track> \| --all [--draft]` | Sync track frontmatter with GitHub labels (read-only on GitHub). Default label is `track/<slug>`; override per-track via `github.labels` in frontmatter. Add `--draft` to preview proposed ADDs/FLAGs without prompting or writing. |
 | `/work-plan duplicates [--min-similarity=0.7]` | Find likely-duplicate issues by title similarity (stdlib difflib). |
 | `/work-plan plan-status [--repo=<key>] [--stamp [--draft]] [--type=plan\|spec]` | **Doc/plan liveness.** "Which of my plan/spec docs actually shipped, half-shipped, or died?" Correlates each plan's declared file-manifest (Create/Modify/Test paths) against git + filesystem — not the unreliable checkboxes. Reports ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less. Read-only by default; `--stamp` writes an idempotent status header into each doc (`--draft` previews, writes nothing). Natural-language triggers: "what's done vs unfinished in `<repo>`", "stamp the plan statuses", "which plans are stale/dead". |
+| `/work-plan plan-confirm --repo=<key> --verdict=shipped\|partial\|dead [--clear] -- <rel>` | **Affirm a human verdict** on one plan doc by writing `verdict_override` into its **frontmatter only** (never body/checkboxes/manifest). `plan-status` then pins that verdict and silences the "shipped but boxes unchecked" lie-gap. Use when a genuinely-shipped plan is flagged red only because nobody ticked its phase checkboxes — confirm it instead of hand-ticking boxes. Public-repo gated (prints `needs_confirm` + token; re-run with `--confirm=<token>`). Natural-language triggers: "that plan really did ship, stop flagging it", "mark `<plan>` as shipped/dead". |
+| `/work-plan plan-ack --repo=<key> [--clear] -- <rel>` | **Durably acknowledge** one plan doc by writing `acknowledged: true` into its **frontmatter only** — a "stop flagging this" that's committed + shared (vs the viewer's per-machine ack). `plan-status` reads it back and demotes the doc. Public-repo gated. Natural-language triggers: "stop flagging this plan for everyone", "acknowledge `<plan>` for good". |
+| `/work-plan plan-baseline --repo=<key> [--clear] -- <rel>` | **Stamp a drift baseline** on one plan doc by writing its current computed verdict to `verdict_baseline` in **frontmatter only**. `plan-status` then flags **drift** when the live verdict diverges — catching a once-shipped plan that silently regressed (files deleted/moved). Distinct from `plan-confirm` (human pin); an override suppresses drift. Public-repo gated. Natural-language triggers: "watch this plan for regressions", "alert me if `<plan>` stops being shipped". |
 
 ## How to invoke
 

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

@@ -0,0 +1,35 @@
+"""auth-status — report whether `gh` is installed and authenticated.
+
+The toolkit's every GitHub read/write goes through `gh`, and the fetch helpers
+deliberately never raise (they return empty on failure). That makes an
+unauthenticated session look like an empty-but-working one. This command is the
+explicit probe the VS Code extension calls at activation so it can fast-fail with
+a clear indicator + a sign-in path instead of rendering a misleadingly empty tree.
+
+Read-only; never mutates anything. Exit code mirrors auth state so a shell caller
+can gate on it: 0 = authenticated, 1 = gh present but not logged in, 2 = gh not
+found.
+"""
+import json
+
+from lib import github_state
+from lib.prompts import parse_flags
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, {"--json"})
+    status = github_state.gh_auth_status()
+
+    if flags.get("--json"):
+        print(json.dumps(status))
+    elif status["authenticated"]:
+        who = f" as {status['user']}" if status.get("user") else ""
+        print(f"✓ Authenticated to GitHub{who}.")
+    elif not status["gh_present"]:
+        print("✗ GitHub CLI (gh) not found on PATH. Install it: https://cli.github.com")
+    else:
+        print("✗ Not logged in to GitHub. Run: gh auth login")
+
+    if status["authenticated"]:
+        return 0
+    return 2 if not status["gh_present"] else 1

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

@@ -0,0 +1,82 @@
+"""close-issue — close a GitHub issue via `gh`, optionally with a comment (#305).
+
+⚠️ This is the toolkit's FIRST and ONLY GitHub-mutating command. Everything else
+is read-only on GitHub. PRs merged to `dev` don't auto-close issues (GitHub only
+auto-closes from the default branch, `main`), so done-but-OPEN issues pile up;
+this closes one explicitly.
+
+The gate is the caller's: the VS Code viewer shows a mandatory "Close on GitHub?"
+modal before every close. There is no needs_confirm token here — unlike the plan
+frontmatter writers, closing doesn't leak private content to a public repo (the
+issue already lives there), so the unconditional UI modal is the right guard
+rather than the public-only token dance.
+
+Usage:
+    work_plan.py close-issue --repo=<key|slug> [--reason=completed|not_planned] [--comment=<text>] -- <number>
+"""
+import json
+import sys
+
+from lib import config as config_mod
+from lib import github_state
+from lib.prompts import parse_flags
+
+VALID_REASONS = {"completed", "not_planned"}
+KNOWN = {"--repo", "--reason", "--comment", "--json"}
+
+
+def _resolve_slug(repo: str, cfg: dict):
+    """A `--repo` value may be a github slug (owner/name) or a config folder key.
+    A slug is used directly; a key is resolved to its slug via config."""
+    if "/" in repo:
+        return repo
+    return config_mod.resolve_github_for_folder(repo, cfg)
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print("ERROR: --repo=<key|slug> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py close-issue --repo=<key|slug> "
+              "[--reason=completed|not_planned] [--comment=<text>] -- <number>",
+              file=sys.stderr)
+        return 2
+    try:
+        number = int(positional[0])
+    except (TypeError, ValueError):
+        print(f"ERROR: issue number must be an integer (got {positional[0]!r}).",
+              file=sys.stderr)
+        return 2
+
+    reason = flags.get("--reason")
+    if reason is True or (reason is not None and reason not in VALID_REASONS):
+        print("ERROR: --reason must be 'completed' or 'not_planned'.", file=sys.stderr)
+        return 2
+    comment = flags.get("--comment")
+    comment = comment if isinstance(comment, str) else None
+
+    try:
+        cfg = config_mod.load_config()
+    except config_mod.ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    slug = _resolve_slug(repo, cfg)
+    if not slug:
+        print(f"ERROR: could not resolve a github slug for --repo={repo!r}.", file=sys.stderr)
+        return 1
+
+    ok, message = github_state.close_issue(slug, number, reason=reason, comment=comment)
+    if not ok:
+        print(f"ERROR: failed to close {slug}#{number}: {message}", file=sys.stderr)
+        return 1
+
+    suffix = " with comment" if comment else ""
+    print(json.dumps({"closed": number, "repo": slug, "reason": reason or "completed"})
+          if flags.get("--json")
+          else f"✓ closed {slug}#{number}{suffix}.")
+    return 0

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

@@ -1,11 +1,50 @@
 """export subcommand — emit the viewer-ready JSON read surface."""
 import json
-from datetime import datetime
-from lib.config import load_config, ConfigError
+from datetime import datetime, date
+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
 from lib.prompts import parse_flags
+from lib import doc_discovery
+from lib import verdict as verdict_mod
+from commands.plan_status import evaluate_doc
+
+
+def _plan_badge(track, cfg, today, dead_days, stall_days):
+    """Resolve a track's declared `plan:` link into an execution badge (#285).
+
+    Returns None when the track declares no plan, `{rel, resolved: false}` when
+    the link can't be resolved (no local clone, or the file is absent), and the
+    full badge — verdict/glyph/files/phases/lie_gap/stalled/override — when it
+    resolves. The verdict is computed by the SAME evaluator plan-status uses, so a
+    badge never disagrees with the Plans view. Only the declared link is trusted;
+    there is no name-matching fallback (#285 acceptance criteria)."""
+    rel = track.meta.get("plan")
+    if not isinstance(rel, str) or not rel.strip():
+        return None
+    rel = rel.strip()
+    local = resolve_local_path_for_folder(track.folder, cfg) if track.folder else None
+    if not local or not local.exists():
+        return {"rel": rel, "resolved": False}
+    doc_path = local / rel
+    if not doc_path.is_file():
+        return {"rel": rel, "resolved": False}
+    doc = doc_discovery.Doc(path=doc_path, rel=rel, kind=doc_discovery.classify_kind(rel))
+    row = evaluate_doc(doc, local, today, dead_days, stall_days)
+    return {
+        "rel": rel,
+        "resolved": True,
+        "verdict": row["verdict"],
+        "glyph": row["glyph"],
+        "files_present": row["files_present"],
+        "files_declared": row["files_declared"],
+        "checkboxes_done": row["checkboxes_done"],
+        "checkboxes_total": row["checkboxes_total"],
+        "lie_gap": row["lie_gap"],
+        "stalled": row["stalled"],
+        "override": row["override"],
+    }
 
 def run(args: list[str]) -> int:
     flags, _ = parse_flags(args, {"--json"})
@@ -60,10 +99,40 @@ 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),
+        })
+
+    # Resolve each track's declared plan link into an execution badge (#285).
+    # Only tracks that declare `plan:` incur the per-doc git/manifest evaluation.
+    today = date.today()
+    cfg_stall = cfg.get("stall_days")
+    stall_days = cfg_stall if isinstance(cfg_stall, int) else verdict_mod.STALL_DAYS
+    plan_by_track: dict[str, dict] = {}
+    for t in tracks:
+        badge = _plan_badge(t, cfg, today, verdict_mod.DEAD_DAYS, stall_days)
+        if badge is not None:
+            plan_by_track[t.name] = badge
+
     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,
+                     plan_by_track=plan_by_track),
         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: