@stylusnexus/work-plan 2026.6.13 → 2026.6.14

package/README.md

@@ -53,6 +53,7 @@ The five essentials you'll use 80% of the time are:
 | `/work-plan orient <track>` | Switching context. ~15-line paste-block of priority / last session / next pick / git state — drop into a fresh Claude Code terminal. |
 | `/work-plan reconcile <track> \| --all \| --repo=<key> [--draft] [--yes]` | Track frontmatter membership drifted from GitHub labels. Use on label-driven tracks only — for hand-curated tracks, use `refresh-md` instead. In an `--all`/`--repo` sweep it also moves issues relabeled from one track to another in the same repo. `--draft` previews proposed ADDs/MOVEs/FLAGs; `--yes` applies without prompting. `--repo=<key>` scopes the sweep to one repo. |
 | `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Runs three steps: ① `refresh-md --all` (pull live GitHub state into every active track's status table), ② `reconcile --all` (sync frontmatter membership against GitHub labels), ③ `duplicates` (flag likely-duplicate issues). `--repo=<key>` scopes steps ① and ② to one repo; step ③ is skipped in scoped mode. |
+| `/work-plan in-progress <n> [--clear]` | Starting or stopping active work on an issue. Adds (or removes with `--clear`) the `work-plan:in-progress` label on GitHub. Repo-resolved from the issue number, or pass `--repo=<key\|slug>` to disambiguate. `brief`/`orient`/the VS Code viewer also detect in-progress automatically from a hot `feat/<n>-`/`fix/<n>-` branch. |
 
 A dozen more subcommands cover slotting new issues into tracks, closing tracks (shipped/abandoned/parked), and one-time priority-label backfill. Three capabilities worth calling out explicitly:
 
@@ -111,7 +112,9 @@ 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.
+> **`brief` and `orient` annotate blocked issues with `⊘ blocked by #N`** — read-only, surfaced from GitHub's native dependency edges, nothing is written back. Cross-repo blockers show as `owner/repo#N`; same-repo duplicates of manually-declared blockers are deduplicated.
+
+> **GitHub access is read-only by default, with three 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 three GitHub-*mutating* actions are all opt-in and gated: `plan-status --issues` **creates** a GitHub issue per partial plan (`gh issue create`, prompts before opening); `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; and `in-progress` (#271) **adds or removes** the `work-plan:in-progress` label on an issue, public-repo gated via the confirm-token flow. Nothing else touches GitHub state.
 
 ## Shared tracks
 
@@ -297,7 +300,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, **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.
+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)
 
@@ -490,7 +493,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; `close-issue` *closes* an issue (`gh issue close`); and `in-progress` *adds or removes* the `work-plan:in-progress` label on an issue. **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.
@@ -521,6 +524,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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). |
@@ -530,6 +534,11 @@ 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. |
+| `close-issue --repo=<key\|slug> [--reason=completed\|not_planned] [--comment=<text>] -- <number>` | ⚠️ A GitHub-mutating command — closes a GitHub issue via `gh issue close`. PRs merged to `dev` don't auto-close issues (GitHub auto-closes only from the default branch), so done-but-OPEN issues pile up; this closes one explicitly. `--reason` maps to GitHub's completed/not-planned; `--comment` posts a closing note. The VS Code viewer gates this behind a mandatory "Close on GitHub? — cannot be undone" modal. |
+| `in-progress <n> [--clear] [--repo=<key\|slug>] [--confirm=<token>]` | ⚠️ A GitHub-mutating command — marks a tracked issue in-progress by adding the `work-plan:in-progress` label (or removes it with `--clear`). Repo-resolved from the issue number; pass `--repo` to disambiguate. The label is auto-created on first use. Public-repo gated (`--confirm=<token>`). Note: `brief`/`orient`/the VS Code viewer also derive in-progress automatically from a hot `feat/<n>-`/`fix/<n>-` branch — the label is for issues with no hot branch yet. |
 
 Run `python3 ~/.claude/skills/work-plan/work_plan.py --help` for the full list with examples.
 
@@ -541,9 +550,15 @@ Every write verb the VS Code extension drives runs **without a TTY** — explici
 
 `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.
 
-`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").
+`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.13+627d944
+2026.06.14+ef58902

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.13",
+  "version": "2026.6.14",
   "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/brief.py

@@ -12,7 +12,9 @@ from lib.prompts import parse_flags
 from lib.git_state import (
     parse_iso_timestamp, gap_seconds_to_label,
     branch_in_progress, commits_ahead, uncommitted_file_count, current_branch,
+    hot_issue_numbers,
 )
+from lib.in_progress import issue_in_progress
 from lib.closure import compute_signals, is_closure_ready
 from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
 from lib.next_up import suggest_next_up
@@ -127,6 +129,7 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
 
     next_up_items = []
     next_up_closed_count = 0
+    hot_nums = hot_issue_numbers(local) if local else set()
     for num in next_up_nums:
         i = issues_by_num.get(num)
         if not i:
@@ -135,11 +138,20 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
         if state in ("CLOSED", "MERGED"):
             next_up_closed_count += 1
             continue
+        manual_blockers = set(meta.get("blockers") or [])
+        blocked_disp = []
+        for e in (i.get("blocked_by") or []):
+            same_repo = e.get("repo") == repo
+            if same_repo and e.get("number") in manual_blockers:
+                continue
+            blocked_disp.append(f"#{e['number']}" if same_repo else f"{e['repo']}#{e['number']}")
         next_up_items.append({
             "number": num, "title": i.get("title", ""),
             "priority": extract_priority(i.get("labels", [])),
             "state": state.lower() or "open",
             "milestone": short_milestone(i.get("milestone")),
+            "in_progress": issue_in_progress(i, hot_nums),
+            "blocked_by_display": blocked_disp,
         })
 
     branch_names = meta.get("github", {}).get("branches") or []

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).
+
+⚠️ A GitHub-mutating command (the others: `in-progress`, and `plan-status --issues`).
+Most of the toolkit 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,51 @@
 """export subcommand — emit the viewer-ready JSON read surface."""
 import json
-from datetime import datetime
+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.git_state import hot_issue_numbers
 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"})
@@ -36,18 +76,19 @@ def run(args: list[str]) -> int:
     issue_map = fetch_export_issues(repo_to_numbers)
 
     # Reassemble per-track lists, preserving each track's declared issue order.
-    issues_by_track: dict[str, list] = {}
+    # Keyed by (repo, name) so same-named tracks in different repos don't collide.
+    issues_by_track: dict[tuple, list] = {}
     visibility: dict[str, object] = {}
     for t in tracks:
         nums = (t.meta.get("github", {}).get("issues")) or []
         if t.repo and nums:
-            issues_by_track[t.name] = [
+            issues_by_track[(t.repo, t.name)] = [
                 issue_map[(t.repo, n)]
                 for n in nums
                 if (t.repo, n) in issue_map
             ]
         else:
-            issues_by_track[t.name] = []
+            issues_by_track[(t.repo, t.name)] = []
         if t.repo and t.repo not in visibility:
             visibility[t.repo] = repo_visibility(t.repo)
 
@@ -77,11 +118,35 @@ def run(args: list[str]) -> int:
             "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
+
+    # Per-track branch heat, keyed (repo, name) — track names collide across repos.
+    hot_by_track: dict = {}
+    for t in tracks:
+        if not t.repo:
+            continue
+        local = resolve_local_path_for_folder(t.folder, cfg) if t.folder else None
+        if local and local.exists():
+            nums = hot_issue_numbers(local)
+            if nums:
+                hot_by_track[(t.repo, t.name)] = nums
+
     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,
-                     config_repos=config_repos),
+                     config_repos=config_repos,
+                     plan_by_track=plan_by_track,
+                     hot_by_track=hot_by_track),
         indent=2,
     ))
     return 0

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

@@ -0,0 +1,110 @@
+"""in-progress — mark/clear a tracked GitHub issue as in-progress via a label (#271).
+
+Writes the work-plan:in-progress label through `gh` (the toolkit's 2nd mutating
+command). Repo targeting is REQUIRED: issue numbers are repo-scoped, so we resolve
+<n> to a unique (repo, n) from the tracked set — rejecting ambiguity — or take an
+explicit --repo. Public-repo writes go behind the same confirm-token gate `set` uses.
+
+Usage:
+    work_plan.py in-progress <n> [--clear] [--repo=<key|slug>] [--confirm=<token>]
+"""
+import json
+import sys
+
+from lib.config import load_config, ConfigError, resolve_github_for_folder
+from lib.tracks import discover_tracks
+from lib.github_state import set_issue_in_progress
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+KNOWN = {"--clear", "--repo", "--confirm"}
+
+
+def _tracked_repos_for(number, cfg):
+    """Return the distinct repo slugs that list `number` in their frontmatter."""
+    repos = []
+    for t in discover_tracks(cfg):
+        if not t.has_frontmatter or not t.repo:
+            continue
+        if number in ((t.meta.get("github", {}) or {}).get("issues") or []):
+            if t.repo not in repos:
+                repos.append(t.repo)
+    return repos
+
+
+def _resolve_repo(number, repo_flag, cfg):
+    """Resolve a unique github slug for `number`.
+
+    With --repo: a slug (owner/name) is used directly; a config key is resolved.
+      The resolved slug is then validated: if the issue IS tracked somewhere and
+      the slug is NOT among those tracked repos, the call is rejected to guard
+      against typos labelling the wrong repo. If the issue is tracked nowhere,
+      --repo is the only targeting option and is accepted as explicit intent.
+    Without --repo: search tracked frontmatter for the distinct repos listing
+      `number`. Returns (slug, None) on success, or (None, error_message).
+    """
+    if isinstance(repo_flag, str) and repo_flag:
+        slug = repo_flag if "/" in repo_flag else resolve_github_for_folder(repo_flag, cfg)
+        if not slug:
+            return (None, f"could not resolve a github slug for --repo={repo_flag!r}.")
+        tracked = _tracked_repos_for(number, cfg)
+        if tracked and slug not in tracked:
+            return (None,
+                    f"issue #{number} is tracked in {tracked}, not {slug!r} — "
+                    f"refusing to label the wrong repo "
+                    f"(drop --repo to use the tracked one, or slot it into a track "
+                    f"in {slug} first).")
+        return (slug, None)
+    repos = _tracked_repos_for(number, cfg)
+    if not repos:
+        return (None, f"issue #{number} is not in any tracked repo — pass --repo=<key|slug>.")
+    if len(repos) > 1:
+        return (None, f"issue #{number} is ambiguous across repos {repos} — "
+                      f"pass --repo=<slug> to disambiguate.")
+    return (repos[0], None)
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+    if not positional:
+        print("usage: work_plan.py in-progress <n> [--clear] [--repo=<key|slug>]",
+              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
+    clear = bool(flags.get("--clear"))
+    repo_flag = flags.get("--repo")
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    slug, problem = _resolve_repo(number, repo_flag, cfg)
+    if not slug:
+        print(f"ERROR: {problem}", file=sys.stderr)
+        return 1
+
+    confirm = flags.get("--confirm")
+    if needs_confirm(slug, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, slug, str(number))
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": f"{slug} is PUBLIC (or visibility unknown); the in-progress "
+                      f"label will be written there.",
+            "token": make_token(slug, str(number)),
+        }))
+        return 0
+
+    ok, message = set_issue_in_progress(slug, number, clear=clear)
+    if not ok:
+        print(f"ERROR: failed to update {slug}#{number}: {message}", file=sys.stderr)
+        return 1
+    verb = "cleared in-progress on" if clear else "marked in-progress"
+    print(f"✓ {verb} {slug}#{number}.")
+    return 0

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

@@ -0,0 +1,71 @@
+"""plan-ack — persist an acknowledgment into a plan/spec doc's YAML frontmatter
+(#286 slice 1).
+
+The VS Code viewer's default "Acknowledge (stop flagging)" persists in
+per-machine `workspaceState` — ephemeral and unshared. This command writes a
+durable `acknowledged: true` into the doc's **frontmatter only** (never the body,
+manifest, checkboxes, or status banner), so the acknowledgment is committed with
+the repo and shared with teammates. `plan-status` reads it back and demotes the
+doc the same way a local ack does.
+
+Usage:
+    work_plan.py plan-ack --repo=<key> [--confirm=<token>] -- <rel>
+    work_plan.py plan-ack --repo=<key> --clear [--confirm=<token>] -- <rel>
+
+`<rel>` is the repo-relative POSIX path of the plan doc (as emitted by
+`plan-status --json`); it is validated to resolve to a real file inside the repo.
+"""
+import sys
+
+from lib import config as config_mod
+from lib import plan_fm
+from lib.prompts import parse_flags
+
+KNOWN = {"--repo", "--clear", "--confirm"}
+
+
+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> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py plan-ack --repo=<key> [--clear] -- <rel>",
+              file=sys.stderr)
+        return 2
+    rel = positional[0]
+    clear = bool(flags.get("--clear"))
+
+    try:
+        cfg = config_mod.load_config()
+    except config_mod.ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    local = config_mod.resolve_local_path_for_folder(repo, cfg)
+    if not local or not local.exists():
+        print(f"repo '{repo}' has no resolvable local path in config", file=sys.stderr)
+        return 2
+
+    doc_path = plan_fm.resolve_doc_path(local, rel)
+    if doc_path is None:
+        print(f"ERROR: '{rel}' is not a file inside {local}", file=sys.stderr)
+        return 1
+
+    slug = config_mod.resolve_github_for_folder(repo, cfg)
+    action = "clearing the acknowledgment on" if clear else f"acknowledging '{rel}' via"
+    if not plan_fm.public_repo_gate(slug, rel, cfg, flags.get("--confirm"), action):
+        return 0
+
+    if clear:
+        if not plan_fm.set_key(doc_path, "acknowledged", None):
+            print(f"✓ {rel} was not acknowledged in frontmatter (nothing to clear).")
+            return 0
+        print(f"✓ cleared acknowledgment on {rel} (frontmatter only).")
+        return 0
+
+    plan_fm.set_key(doc_path, "acknowledged", True)
+    print(f"✓ {rel} acknowledged — wrote acknowledged:true to frontmatter only.")
+    return 0