@stylusnexus/work-plan 2026.6.13-2 → 2026.6.14-1

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 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.
+> **`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
 
@@ -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.
-- **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.
+- **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.
@@ -534,6 +537,8 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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.
 

package/VERSION

@@ -1 +1 @@
-2026.06.13+22f59a8
+2026.06.14+6579bf7

package/package.json

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

@@ -1,7 +1,7 @@
 """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
+⚠️ 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.
 

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

@@ -4,6 +4,7 @@ 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
@@ -75,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)
 
@@ -127,12 +129,24 @@ def run(args: list[str]) -> int:
         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,
-                     plan_by_track=plan_by_track),
+                     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/where_was_i.py

@@ -31,7 +31,9 @@ from lib.github_state import fetch_issues, short_milestone
 from lib.git_state import (
     parse_iso_timestamp,
     current_branch, uncommitted_file_count, commits_ahead,
+    hot_issue_numbers,
 )
+from lib.in_progress import issue_in_progress
 from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
 
 
@@ -122,6 +124,8 @@ def _orient_track(track) -> int:
     titles_by_num: dict[int, str] = {}
     states_by_num: dict[int, str] = {}
     milestones_by_num: dict[int, str] = {}
+    inprog_by_num: dict = {}
+    blocked_by_num: dict = {}
     if track.repo and next_up:
         wanted = next_up[:4]
         fetched = fetch_issues(track.repo, wanted)
@@ -129,6 +133,18 @@ def _orient_track(track) -> int:
             titles_by_num[i["number"]] = i.get("title", "")
             states_by_num[i["number"]] = (i.get("state") or "").upper()
             milestones_by_num[i["number"]] = short_milestone(i.get("milestone"))
+        hot = hot_issue_numbers(track.local_path) if track.local_path else set()
+        manual_blockers = set(track.meta.get("blockers") or [])
+        for i in fetched:
+            inprog_by_num[i["number"]] = issue_in_progress(i, hot)
+            disp = []
+            for e in (i.get("blocked_by") or []):
+                same = e.get("repo") == track.repo
+                if same and e.get("number") in manual_blockers:
+                    continue
+                disp.append(f"#{e['number']}" if same else f"{e['repo']}#{e['number']}")
+            if disp:
+                blocked_by_num[i["number"]] = disp
 
     print(_top_rule(slug))
     print(f"Priority: {priority}  ·  Milestone: {milestone}  ·  Repo: {repo}")
@@ -150,7 +166,9 @@ def _orient_track(track) -> int:
         pick_title = titles_by_num.get(pick_num, "")
         pick_suffix = _state_suffix(states_by_num.get(pick_num))
         pick_ms = _milestone_prefix(milestones_by_num.get(pick_num))
-        print(f"Next pick: #{pick_num}  {pick_ms}{pick_title}{pick_suffix}".rstrip())
+        print(f"Next pick: #{pick_num}  {pick_ms}{pick_title}{pick_suffix}"
+              f"{_inprog_suffix(inprog_by_num.get(pick_num, False))}"
+              f"{_blocked_suffix(blocked_by_num.get(pick_num))}".rstrip())
         if _is_closed(states_by_num.get(pick_num)):
             print(f"  ⚠  next_up:[0] has shipped — run `/work-plan handoff {slug}` to rotate")
         rest = next_up[1:4]
@@ -161,7 +179,9 @@ def _orient_track(track) -> int:
                 title = titles_by_num.get(num, "")
                 suffix = _state_suffix(states_by_num.get(num))
                 ms = _milestone_prefix(milestones_by_num.get(num))
-                print(f"  #{num}  {ms}{title}{suffix}".rstrip())
+                print(f"  #{num}  {ms}{title}{suffix}"
+                      f"{_inprog_suffix(inprog_by_num.get(num, False))}"
+                      f"{_blocked_suffix(blocked_by_num.get(num))}".rstrip())
     else:
         print("Next pick: (none set — run `/work-plan handoff` to set one)")
 
@@ -235,6 +255,14 @@ def _state_suffix(state: Optional[str]) -> str:
     return "  (closed)" if _is_closed(state) else ""
 
 
+def _inprog_suffix(flag: bool) -> str:
+    return "  ▶ in-progress" if flag else ""
+
+
+def _blocked_suffix(disp: Optional[list]) -> str:
+    return ("  ⊘ blocked by " + ", ".join(disp)) if disp else ""
+
+
 def _milestone_prefix(ms: Optional[str]) -> str:
     return f"[{ms}] " if ms else ""
 

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

@@ -52,10 +52,22 @@ def group_issues_by_milestone(issues, milestone_alignment=None):
     return groups
 
 
-def normalize_issue(i: dict) -> dict:
+def normalize_issue(i: dict, in_progress: bool = False,
+                    in_progress_label: bool = False,
+                    blocked_by=None, blocking=None) -> dict:
     """Reshape a raw gh issue row into the viewer's `Issue` shape
-    ({number,title,state,assignee,milestone}). Shared by the export and the
-    `list-open-issues` command (#282) so both emit an identical issue surface."""
+    ({number,title,state,assignee,milestone,in_progress,in_progress_label,
+    blocked_by,blocking}).
+    Shared by the export and the `list-open-issues` command (#282) so both
+    emit an identical issue surface.
+
+    `in_progress` is the UNION signal (hot branch OR label) — used by the
+    badge.  `in_progress_label` reflects LABEL presence only — used by the
+    toggle button so it accurately shows Mark/Clear for the label, not the
+    union.
+    `blocked_by` / `blocking` are lists of cross-issue dependency refs
+    (#257); default to [] when absent.
+    """
     state = (i.get("state") or "OPEN").lower()
     return {
         "number": i.get("number"),
@@ -63,16 +75,35 @@ def normalize_issue(i: dict) -> dict:
         "state": "closed" if state in ("closed", "merged") else "open",
         "assignee": (format_assignees(i) if i.get("assignees") else "—"),
         "milestone": short_milestone(i.get("milestone")) or None,
+        "in_progress": bool(in_progress),
+        "in_progress_label": bool(in_progress_label),
+        "blocked_by": list(blocked_by or []),
+        "blocking": list(blocking or []),
     }
 
 
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None, config_repos=None,
-                 plan_by_track=None) -> dict:
+                 plan_by_track=None, hot_by_track=None) -> dict:
     plan_by_track = plan_by_track or {}
+    hot_by_track = hot_by_track or {}
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
     for t in tracks:
-        issues = [normalize_issue(i) for i in issues_by_track.get(t.name, [])]
+        from lib.in_progress import issue_in_progress, IN_PROGRESS_LABEL
+        hot = hot_by_track.get((t.repo, t.name), set())
+        raw = issues_by_track.get((t.repo, t.name), [])
+        issues = [
+            normalize_issue(
+                i,
+                in_progress=issue_in_progress(i, hot),
+                in_progress_label=IN_PROGRESS_LABEL in {
+                    l.get("name") for l in (i.get("labels") or [])
+                },
+                blocked_by=i.get("blocked_by"),
+                blocking=i.get("blocking"),
+            )
+            for i in raw
+        ]
         milestone_alignment = t.meta.get("milestone_alignment")
         issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")

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

@@ -1,4 +1,5 @@
 """Local git queries + time helpers."""
+import re
 import subprocess
 from datetime import date, datetime, timedelta
 from pathlib import Path
@@ -131,6 +132,76 @@ def branch_in_progress(branch_name: str, repo_path: Path) -> bool:
     return _has_recent_commits(branch_name, repo_path, hours=24)
 
 
+# Maps a conventional branch name to its issue number. Anchored at start and
+# requires a trailing '-' so `feat/2710-x` captures 2710, never the `271`
+# substring. Only feat/ and fix/ — `work-plan/plan` (#260) carries no issue
+# number, and there is no `plan/<n>-` convention.
+_BRANCH_ISSUE_RE = re.compile(r"^(?:feat|fix)/(\d+)-")
+
+
+# Per-process memo for hot_issue_numbers, keyed by resolved repo path. A single
+# export/brief/orient run calls hot_issue_numbers once per track, but many tracks
+# share one clone (e.g. ~25 CritForge tracks → one checkout). Live git state can't
+# change mid-run, so caching by resolved path turns an O(tracks) rescan into
+# O(distinct clones). The CLI is one-shot, so the cache dies with the process;
+# tests reset it via _reset_hot_cache(). (#257 follow-up: pre-memo this was
+# ~40s × 25 tracks ≈ 16min for CritForge on every VS Code reload.)
+_HOT_CACHE: dict = {}
+
+
+def _reset_hot_cache() -> None:
+    """Clear the hot_issue_numbers memo (test hook; not used in production)."""
+    _HOT_CACHE.clear()
+
+
+def hot_issue_numbers(repo_path: Path) -> set:
+    """Issue numbers with a 'hot' (in-progress) feat/<n>-/fix/<n>- branch in `repo_path`.
+
+    A branch is hot when its tip was committed in the last 24h, OR it is the
+    checked-out branch with uncommitted changes. Enumerates every branch and its
+    tip commit time in ONE `git for-each-ref` call (the recency signal), then does
+    a single current-branch/uncommitted check — so the cost is O(1) git calls, not
+    O(branches). (Previously each of the N branches incurred ~4 git subprocesses
+    via branch_in_progress; on a clone with hundreds of feat/fix branches that was
+    tens of seconds per call.) Result is memoized per resolved path for the process.
+
+    Failure contract: any git enumeration failure -> empty set (not cached, so a
+    later call in the same run can still succeed). Never raises.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return set()
+    key = str(Path(repo_path).resolve())
+    cached = _HOT_CACHE.get(key)
+    if cached is not None:
+        return cached
+    proc = _git(repo_path, "for-each-ref", "refs/heads",
+                "--format=%(refname:short)%09%(committerdate:unix)")
+    if proc is None or proc.returncode != 0:
+        return set()
+    cutoff = (datetime.now() - timedelta(hours=24)).timestamp()
+    hot = set()
+    candidates: dict = {}  # feat/fix branch name -> issue number
+    for line in proc.stdout.splitlines():
+        name, _tab, ts = line.strip().partition("\t")
+        m = _BRANCH_ISSUE_RE.match(name)
+        if not m:
+            continue
+        num = int(m.group(1))
+        candidates[name] = num
+        try:
+            if float(ts) >= cutoff:
+                hot.add(num)
+        except ValueError:
+            pass  # missing/odd committerdate -> not hot by recency
+    # Uncommitted-changes-on-the-checked-out-branch case: 2 git calls total,
+    # independent of branch count (mirrors branch_in_progress's first clause).
+    cur = current_branch(repo_path)
+    if cur in candidates and has_uncommitted(repo_path):
+        hot.add(candidates[cur])
+    _HOT_CACHE[key] = hot
+    return hot
+
+
 def last_commit_date(branch_name: str, repo_path: Path) -> Optional[datetime]:
     """Most recent commit timestamp on branch (naive)."""
     if not repo_path or not Path(repo_path).exists():

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

@@ -5,6 +5,8 @@ import subprocess
 from concurrent.futures import ThreadPoolExecutor
 from typing import Iterable, Optional
 
+from lib.in_progress import IN_PROGRESS_LABEL
+
 PRIORITY_LABELS = ("priority/P0", "priority/P1", "priority/P2", "priority/P3")
 DEFAULT_PRIORITY = "P3"
 
@@ -29,8 +31,9 @@ def _valid_repo(repo: str) -> bool:
 
 
 def close_issue(repo: str, number: int, reason=None, comment=None) -> tuple:
-    """Close a GitHub issue via `gh issue close` — the toolkit's ONLY
-    GitHub-mutating call (#305). Everything else here is read-only.
+    """Close a GitHub issue via `gh issue close` — one of the toolkit's
+    GitHub-mutating calls (also `set_issue_in_progress`, `create_issue`).
+    Everything else here is read-only.
 
     Returns (ok, message). `reason` ∈ {completed, not_planned} maps to
     `--reason`; `comment` (if given) posts a closing comment. The issue number
@@ -54,6 +57,36 @@ def close_issue(repo: str, number: int, reason=None, comment=None) -> tuple:
     return (True, (proc.stdout or f"closed #{number}").strip())
 
 
+def set_issue_in_progress(repo: str, number: int, clear: bool = False) -> tuple:
+    """Add or remove the work-plan:in-progress label on a GitHub issue (#271).
+
+    The toolkit's second GitHub-mutating call (close_issue is the first). On add,
+    the label is created first (`--force` is idempotent: updates color/description
+    if it already exists) so `--add-label` can't fail on a missing label. Both gh
+    calls are --repo-qualified — issue numbers are repo-scoped. Returns (ok, message);
+    never raises. number->str for argv, repo validated owner/name, so neither injects.
+    """
+    if not _valid_repo(repo):
+        return (False, f"invalid repo '{repo}'")
+    try:
+        if not clear:
+            create = ["gh", "label", "create", IN_PROGRESS_LABEL, "--repo", repo,
+                      "--color", "FBCA04",
+                      "--description", "Actively being worked (work-plan)", "--force"]
+            proc = subprocess.run(create, capture_output=True, text=True, timeout=GH_TIMEOUT)
+            if proc.returncode != 0:
+                return (False, (proc.stderr or proc.stdout or "gh label create failed").strip())
+        flag = "--remove-label" if clear else "--add-label"
+        edit = ["gh", "issue", "edit", str(int(number)), "--repo", repo, flag, IN_PROGRESS_LABEL]
+        proc = subprocess.run(edit, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except Exception as e:
+        return (False, f"gh in-progress write failed: {e}")
+    if proc.returncode != 0:
+        return (False, (proc.stderr or proc.stdout or "gh issue edit failed").strip())
+    verb = "cleared" if clear else "marked"
+    return (True, (proc.stdout or f"{verb} #{number} in-progress").strip())
+
+
 def gh_auth_status() -> dict:
     """Probe `gh` authentication so callers can fast-fail instead of silently
     degrading (#auth). Returns:
@@ -161,7 +194,8 @@ def _normalize_gql_node(node) -> Optional[dict]:
     expect (labels as [{name}], assignees as [{login}], milestone as {title}|None).
     None for a null node.
     On success returns a dict with keys: number, title, state, labels, milestone,
-    closedAt, body, url, updatedAt, assignees."""
+    closedAt, body, url, updatedAt, assignees, blocked_by, blocking,
+    deps_truncated."""
     if not node:
         return None
     labels = [{"name": l.get("name")} for l in
@@ -169,6 +203,20 @@ def _normalize_gql_node(node) -> Optional[dict]:
     assignees = [{"login": a.get("login")} for a in
                  ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
     ms = node.get("milestone")
+
+    def _deps(key):
+        conn = node.get(key) or {}
+        nodes = conn.get("nodes") or []
+        open_edges = [{"number": n.get("number"),
+                       "repo": (n.get("repository") or {}).get("nameWithOwner"),
+                       "title": n.get("title", "")}
+                      for n in nodes if (n.get("state") or "").upper() == "OPEN"]
+        truncated = (conn.get("totalCount") or 0) > len(nodes)
+        return open_edges, truncated
+    blocked_by, _bb_trunc = _deps("blockedBy")
+    blocking, _bl_trunc = _deps("blocking")
+    deps_truncated = _bb_trunc or _bl_trunc
+
     return {
         "number": node.get("number"),
         "title": node.get("title", ""),
@@ -180,6 +228,9 @@ def _normalize_gql_node(node) -> Optional[dict]:
         "url": node.get("url", ""),
         "updatedAt": node.get("updatedAt"),
         "assignees": assignees,
+        "blocked_by": blocked_by,
+        "blocking": blocking,
+        "deps_truncated": deps_truncated,
     }
 
 
@@ -187,7 +238,7 @@ def _normalize_gql_node(node) -> Optional[dict]:
 # Kept as a module-level constant so _gql_query can parameterize at the call site.
 _GQL_FIELDS_FULL = (
     "number title state"
-    " labels(first: 20) { nodes { name } }"
+    " labels(first: 50) { nodes { name } }"
     " milestone { title }"
     " closedAt body url updatedAt"
     " assignees(first: 10) { nodes { login } }"
@@ -195,19 +246,33 @@ _GQL_FIELDS_FULL = (
 
 _GQL_FIELDS_LEAN = (
     "number title state"
+    " labels(first: 50) { nodes { name } }"
     " assignees(first: 10) { nodes { login } }"
     " milestone { title }"
 )
 
+# Issue dependency edges (#257). Issue-ONLY: PullRequest has no blockedBy/blocking,
+# and _gql_query shares the base field set across both fragments — so these are
+# appended only to the `... on Issue` fragment. No server-side state filter exists
+# (the connection takes only orderBy + cursor args), so OPEN-filtering is done in
+# _normalize_gql_node; totalCount detects first:50 truncation (confirmed live field).
+_GQL_ISSUE_DEPS = (
+    " blockedBy(first: 50) { totalCount nodes { number state title repository { nameWithOwner } } }"
+    " blocking(first: 50) { totalCount nodes { number state title repository { nameWithOwner } } }"
+)
+
 
 def _gql_query(owner: str, name: str, numbers: list,
                fields: str = _GQL_FIELDS_LEAN) -> str:
     """Build a batched GraphQL query for issueOrPullRequest nodes.
     `fields` selects the GQL field set; _GQL_FIELDS_LEAN for export, _GQL_FIELDS_FULL
-    for fetch_issues (which needs labels, closedAt, body, url, updatedAt)."""
+    for fetch_issues (which needs labels, closedAt, body, url, updatedAt).
+    _GQL_ISSUE_DEPS is appended to the Issue fragment only — PullRequest does not
+    expose blockedBy/blocking fields."""
     aliases = "\n".join(
         f'  i{n}: issueOrPullRequest(number: {int(n)}) {{ '
-        f'... on Issue {{ {fields} }} ... on PullRequest {{ {fields} }} }}'
+        f'... on Issue {{ {fields}{_GQL_ISSUE_DEPS} }} '
+        f'... on PullRequest {{ {fields} }} }}'
         for n in numbers
     )
     return f'query {{ repository(owner: "{owner}", name: "{name}") {{\n{aliases}\n}} }}'