@stylusnexus/work-plan 2026.6.15 → 2026.6.16

package/README.md

@@ -48,11 +48,11 @@ The five essentials you'll use 80% of the time are:
 
 | Command | When |
 |---|---|
-| `/work-plan brief` | Morning. Multi-track snapshot — what's on your plate across every active track. Add `--repo=<key>` to scope to one project. |
+| `/work-plan brief` | Morning. Multi-track snapshot — what's on your plate across every active track. Run from inside a configured repo's checkout and it **auto-scopes to that repo** (one-line banner; `--repo=all` shows everything). Add `--repo=<key>` to scope to a specific project. |
 | `/work-plan handoff <track>` | End of a work block. Captures what you touched. Use `--auto-next` for an algorithmic priority-sorted `next_up` (no LLM), `--set-next 1,2,3` for explicit numbers, or pair with Claude in chat for a curated pick. |
 | `/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 hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Runs four steps: ① `refresh-md --all` (pull live GitHub state into every active track's status table), ② `reconcile --all` (sync frontmatter membership against GitHub labels), ③ `dedupe-tiers` (report shared/private duplicate tracks, no deletes), ④ `duplicates` (flag likely-duplicate issues). `--repo=<key>` scopes steps ①–③ 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:
@@ -104,12 +104,12 @@ flowchart TB
 
 - **Morning** → `brief` shows multi-track plate, then `orient <track>` produces a ~15-line paste-block to drop into a fresh agent session.
 - **End of work block** → `handoff <track>` captures what you touched. Three ways to set `next_up` for tomorrow:
-  - `handoff <track> --auto-next` — algorithmic (no LLM): top-3 by priority then most-recently-updated, blockers excluded. Interactive `[Y/n/edit]` prompt — accept, edit, or skip.
+  - `handoff <track> --auto-next` — algorithmic (no LLM): top-3 by priority then most-recently-updated, blockers excluded. Interactive `[Y/n/edit]` prompt — accept, edit, or skip. (`--suggest-next` is the read-only, non-interactive sibling: it prints the same suggestion as JSON and writes nothing — the feed the VS Code **Suggest Next-Up (auto)** picker confirms, since the TTY prompt can't run under the extension.)
   - `handoff <track> --set-next 4167,4148` — explicit numbers when you know exactly which issues are next.
   - Free-form via Claude in your agent session, which can review project memory and write a curated list back. The two `--*-next` flags are the no-LLM paths.
   - For tracks where you don't want to bother curating at all, set `next_up_auto: true` in the track's frontmatter — `brief` will then derive the list live each invocation, ignoring whatever's stored.
-  - **Ranking presets** — when `next_up_auto: true` is on, the default ranking is `flow` (milestone → dependency → priority → recency). Override per-track with `set-next-up <track> --preset=<name>`, or set `next_up_default: <name>` in your config for a global fallback. Named presets: `flow` (the default), `priority-driven` (priority first, no milestone bias — good for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work). Custom criterion order: `set-next-up <track> --order=aging,priority,dependency`. Clear a track's override with `--clear`.
-- **Weekly** → `hygiene` runs `refresh-md --all` + `reconcile --all` + `duplicates` in sequence to keep status icons, GitHub labels, and dedup state honest.
+  - **Ranking presets** — when `next_up_auto: true` is on, the default ranking is `flow` (milestone → dependency → priority → recency). Override per-track with `set-next-up <track> --preset=<name>`, or set `next_up_default: <name>` in your config for a global fallback. Named presets: `flow` (the default), `priority-driven` (priority first, no milestone bias — good for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work). Custom criterion order: `set-next-up <track> --order=aging,priority,dependency`. Clear a track's override with `--clear`. Toggle auto-derivation itself with `--auto=on|off` (no hand-editing frontmatter required).
+- **Weekly** → `hygiene` runs `refresh-md --all` + `reconcile --all` + `dedupe-tiers` (report-only) + `duplicates` in sequence to keep status icons, GitHub labels, tier dedup, and issue-dedup state honest.
 
 > **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.
 
@@ -280,7 +280,7 @@ A skill has two distinct contracts: (1) the underlying **CLI** that does the wor
 
 | Tool | Install command | Then invoke as |
 |---|---|---|
-| **npm (standalone CLI / any editor)** | `npm install -g @stylusnexus/work-plan` (requires `python3` + `yq` + `gh` already on PATH — the postinstall warns if any are missing). | `work-plan <subcommand>` |
+| **npm (standalone CLI / any editor)** | `npm install -g @stylusnexus/work-plan` (requires `python3` + `yq` + `gh` already on PATH — the CLI warns on first run if any are missing). | `work-plan <subcommand>` |
 | **Claude Code** | **Plugin (recommended):** `/plugin marketplace add stylusnexus/agent-plugins` → `/plugin install work-plan@stylus-nexus`. Or script: `./install.sh` / `.\install.ps1` | Plugin: `/work-plan:brief` … `/work-plan:run <sub>`. Script: bare `/work-plan <subcommand>` |
 | **Codex** | **Plugin:** `codex plugin marketplace add stylusnexus/agent-plugins` → `codex plugin add work-plan@stylus-nexus`. Or script: `./install.sh --target=$HOME/.agents` | Plugin: `@work-plan` / `/skills`. Script: direct CLI |
 | **Cursor** | Skip installer. Clone repo + copy `shims/cursor/work-plan.cursorrules` into your project's `.cursorrules` (or merge it in) | `python3 <toolkit>/skills/work-plan/work_plan.py <sub>` — alias `wp` recommended |
@@ -301,7 +301,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, 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.
+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) that draws **GitHub-native blocked-by edges**, per-track detail with an **open/closed progress bar**, a one-click **Plan** link, a **per-issue in-progress badge + toggle**, expandable **blocked-by / blocking dependency chips**, 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, **next-up controls** — a **Set Next-Up** button and a **Set Next-Up Order…** preset picker (`flow` / `priority-driven` / `backlog`) with the active preset shown inline, 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)
 
@@ -510,20 +510,22 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 
 | Subcommand | What it does |
 |---|---|
-| `brief [--repo=<key>]` | Multi-track snapshot of all active tracks across configured repos. `--repo=<key>` filters to one project (matches the folder name under `notes_root` or the `org/repo` GitHub slug; archived-reopen callouts are also scoped). |
+| `brief [--repo=<key> \| --repo=all]` | Multi-track snapshot of all active tracks across configured repos. When `--repo` is omitted and you're inside a configured repo's checkout, `brief` **auto-scopes to that repo** (resolved by clone path, then git remote) and prints a one-line banner; `--repo=all` forces the full cross-repo view. `--repo=<key>` filters to one project explicitly (matches the folder name under `notes_root` or the `org/repo` GitHub slug). In all cases the archived-reopen callouts are scoped to the same repo. Disable cwd auto-scope with `brief_auto_scope: false` in `config.yml`. |
+| `which-repo [--json]` | Resolve the current directory to one configured repo — by local clone path first, then the git `origin` remote. Prints the matched config key + GitHub slug, or reports no match. Read-only; it's the shared resolver behind `brief`'s cwd auto-scope and the VS Code viewer's repo auto-focus. |
 | `handoff <track> [--auto-next \| --set-next 1,2,3]` | Wrap up a work block. Writes a `### Session — <ts>` entry. `--auto-next` suggests a priority-sorted top-3 from open issues (interactive: apply / edit / skip). `--set-next 1,2,3` is the explicit form — note it writes the session entry too; for a field-only `next_up` change with no session log, use `set next_up=…`. Without either flag, just captures the session summary and reads any pre-existing `next_up`. |
 | `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. 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. |
+| `hygiene [--repo=<key>]` | Weekly all-in-one: `refresh-md` + `reconcile` + `dedupe-tiers` (report-only) + `duplicates`. With `--repo=<key>`, steps 1–3 scope to that repo and the global `duplicates` step is skipped. |
+| `dedupe-tiers [--repo=<key>] [--apply]` | Remove private track copies that a shared twin in a repo's `.work-plan/` supersedes (#359). When a track is promoted to the shared tier, its private original under `notes_root` is sometimes left behind (bulk/manual promotion, or a failed unlink during `push-track`) — `discover_tracks` then warns `exists in both shared and private` on every run with no cleanup path. This removes the safe orphans and **refuses** any whose private copy references issue numbers the shared one lacks (no silent data loss; the invariant is `issue_refs(private) ⊆ issue_refs(shared)`). Covers active and archived tiers. Default is a **dry-run report**; `--apply` deletes (auto-committed to `notes_root`, so undoable via `notes-vcs undo`). `--repo=<key>` scopes to one repo. |
 | `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>] [--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-next-up <track> (--preset=<name> \| --order=a,b,c \| --clear) [--repo=<key>] [--confirm=<token>]` | Configure the ranking preset used when `next_up_auto: true` computes a suggestion. `--preset` sets a named preset: `flow` (default — milestone → dependency → priority → recency), `priority-driven` (priority first, ignores milestone bias, for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work), or `custom` (requires `--order`). `--order=a,b,c` sets a custom comma-separated criterion list (`milestone`, `dependency`, `priority`, `recency`, `aging`). `--clear` reverts to the global `next_up_default` config or the default `flow`. Writes `next_up_order` into the track's frontmatter; does NOT touch the `next_up` issue-list. Global default: add `next_up_default: <preset>` to `~/.claude/work-plan/config.yml`. Public-repo gated. |
+| `set-next-up <track> (--preset=<name> \| --order=a,b,c \| --clear \| --auto=on\|off) [--repo=<key>] [--confirm=<token>]` | Configure the ranking preset and/or auto-derivation flag for a track's next_up list. `--preset` sets a named preset: `flow` (default — milestone → dependency → priority → recency), `priority-driven` (priority first, ignores milestone bias, for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work), or `custom` (requires `--order`). `--order=a,b,c` sets a custom comma-separated criterion list (`milestone`, `dependency`, `priority`, `recency`, `aging`). `--clear` reverts to the global `next_up_default` config or the default `flow`. `--auto=on` activates `next_up_auto` so brief/orient/export auto-derive the next-up list live from the ranking preset (ignoring the curated list); `--auto=off` clears it to revert to the curated list. `--auto` can be used standalone or combined with `--preset`/`--order`/`--clear`. Writes `next_up_order` and/or `next_up_auto` into the track's frontmatter; does NOT touch the `next_up` issue-list. Global default: add `next_up_default: <preset>` to `~/.claude/work-plan/config.yml`. 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. |

package/VERSION

@@ -1 +1 @@
-2026.06.15+d52d670
+2026.06.16+ebd6045

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.15",
+  "version": "2026.6.16",
   "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"
@@ -8,14 +8,10 @@
   "files": [
     "bin/",
     "skills/work-plan/",
-    "scripts/npm-check-deps.js",
     "VERSION",
     "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "postinstall": "node scripts/npm-check-deps.js"
-  },
   "engines": {
     "node": ">=18"
   },

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

@@ -1,8 +1,10 @@
 """brief subcommand — fully featured."""
+import os
 from datetime import datetime
 from pathlib import Path
 
 from lib.config import load_config, ConfigError
+from lib.cwd_repo import resolve_repo_for_dir
 from lib.tracks import (
     discover_tracks, discover_archived_tracks, filter_tracks_by_repo,
     priority_rank, recency_sort_key,
@@ -24,9 +26,9 @@ from lib.render import time_aware_framing, render_track_row, render_archived_reo
 
 def run(args: list[str]) -> int:
     flags, _ = parse_flags(args, {"--repo"})
-    repo_key = flags.get("--repo")
-    if repo_key is True:
-        print("usage: work_plan.py brief [--repo=<key>]")
+    repo_arg = flags.get("--repo")
+    if repo_arg is True:
+        print("usage: work_plan.py brief [--repo=<key> | --repo=all]")
         return 2
 
     try:
@@ -36,15 +38,39 @@ def run(args: list[str]) -> int:
         return 1
 
     tracks = discover_tracks(cfg)
+
+    # Resolve the effective scope key ONCE, then thread it through both the track
+    # filter and the archived-reopen pass so the two can never diverge (#358):
+    #   explicit --repo=<key> → scope to it (unchanged behavior, no banner)
+    #   explicit --repo=all   → force the full view (no scope, no auto-detect)
+    #   --repo omitted        → auto-detect from cwd (unless opted out); banner on hit
+    auto_scoped = False
+    if isinstance(repo_arg, str):
+        repo_key = None if repo_arg.lower() == "all" else repo_arg
+    else:
+        repo_key = None
+        if cfg.get("brief_auto_scope", True):
+            match = resolve_repo_for_dir(cfg, os.getcwd())
+            # Only auto-scope when the detected repo actually has tracks — a
+            # convenience must never hide tracks you'd otherwise see.
+            if match and filter_tracks_by_repo(tracks, match["key"]):
+                repo_key = match["key"]
+                auto_scoped = True
+
     if repo_key:
         scoped = filter_tracks_by_repo(tracks, repo_key)
         if not scoped:
+            # Reachable only via an explicit --repo (the auto path above already
+            # guaranteed a non-empty match).
             print(f"No tracks found for repo '{repo_key}'.")
             available = sorted((cfg.get("repos") or {}).keys())
             if available:
                 print(f"Configured repo keys: {', '.join(available)}")
             return 0
         tracks = scoped
+        if auto_scoped:
+            print(f"Scoped to repo '{repo_key}' (cwd). Use --repo=all to see everything.")
+            print()
     active = [t for t in tracks if t.has_frontmatter
               and t.meta.get("status") in ("active", "in-progress", "blocked")]
 

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

@@ -0,0 +1,104 @@
+"""dedupe-tiers — remove private track copies shadowed by a shared twin (#359).
+
+When a track is promoted to the shared tier (a repo's `.work-plan/`), the private
+original under `notes_root` is normally moved out by `push-track`. But bulk or
+manual promotion — or a failed unlink mid-promote — leaves the private copy
+behind. `discover_tracks` then resolves the collision ("using shared") but warns
+on EVERY invocation, with no built-in way to clean up.
+
+This verb removes the orphaned private copies that their shared twin supersedes,
+and REFUSES to touch any whose private copy still references issue numbers the
+shared one lacks — so no tracked work is ever silently dropped. The no-data-loss
+invariant is `issue_refs(private) ⊆ issue_refs(shared)`.
+
+Default is a dry-run report. Pass `--apply` to delete the safe orphans; the
+deletion lands in notes_root and the dispatcher's auto-commit makes it undoable.
+
+Usage:
+    work_plan.py dedupe-tiers [--repo=<key>] [--apply]
+"""
+import sys
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import find_tier_duplicates, issue_refs
+from lib.prompts import parse_flags
+
+KNOWN = {"--repo", "--apply"}
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, KNOWN)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py dedupe-tiers [--repo=<key>] [--apply]",
+              file=sys.stderr)
+        return 2
+    apply = bool(flags.get("--apply"))
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    pairs = find_tier_duplicates(cfg)
+    if repo_key:
+        k = repo_key.lower()
+        pairs = [(s, p) for (s, p) in pairs
+                 if (s.folder and s.folder.lower() == k)
+                 or (s.repo and s.repo.lower() == k)]
+
+    if not pairs:
+        scope = f" for repo '{repo_key}'" if repo_key else ""
+        print(f"No shared/private duplicate tracks found{scope}. Nothing to dedupe.")
+        return 0
+
+    safe: list = []      # (shared, private) — private issue refs ⊆ shared
+    diverged: list = []  # (shared, private, extra_refs) — private has unique refs
+    for s, p in pairs:
+        extra = issue_refs(p) - issue_refs(s)
+        if extra:
+            diverged.append((s, p, extra))
+        else:
+            safe.append((s, p))
+
+    print(f"Found {len(pairs)} shared/private duplicate track(s):")
+    print(f"  {len(safe)} safe to remove (private issue refs ⊆ shared)")
+    print(f"  {len(diverged)} diverged — kept for manual review")
+    print()
+
+    for s, p in safe:
+        print(f"  ✓ {p.name}  (repo {s.repo or s.folder}) — private superseded by shared")
+        print(f"      private: {p.path}")
+    for s, p, extra in diverged:
+        refs = ", ".join(f"#{n}" for n in sorted(extra))
+        print(f"  ⚠ {p.name}  (repo {s.repo or s.folder}) — private has issue refs "
+              f"not in shared: {refs}")
+        print(f"      KEPT: {p.path} — reconcile by hand")
+
+    if not apply:
+        print()
+        if safe:
+            print(f"Dry run. Re-run with --apply to remove {len(safe)} private orphan(s).")
+        else:
+            print("Dry run. Nothing safe to remove automatically.")
+        return 0
+
+    if not safe:
+        print()
+        print("Nothing removed — every duplicate diverged and needs manual review.")
+        return 0
+
+    removed = 0
+    for s, p in safe:
+        try:
+            Path(p.path).unlink()
+            removed += 1
+        except OSError as e:
+            print(f"WARN: could not remove {p.path}: {e}", file=sys.stderr)
+
+    print()
+    print(f"Removed {removed} private orphan(s). "
+          f"{len(diverged)} diverged track(s) left for manual review.")
+    return 0

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

@@ -2,7 +2,7 @@
 import json
 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.tracks import discover_tracks, find_tier_duplicates, issue_refs
 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
@@ -93,11 +93,19 @@ def run(args: list[str]) -> int:
             visibility[t.repo] = repo_visibility(t.repo)
 
     # Compute untracked: open issues not referenced by any track, per repo.
+    # Iterate over every repo that has ANY track — NOT just repos in
+    # repo_to_numbers (which only collects tracks whose github.issues is
+    # non-empty). A repo whose only track has `issues: []` must still get its
+    # open issues surfaced as untracked; otherwise creating an empty track in a
+    # previously-trackless repo makes its open issues vanish — neither in the
+    # (empty) track nor in untracked, and the viewer's trackless fallback
+    # (treeModel.mergeFetchedUntracked) shuts off the moment a track exists (#342).
     # One `gh issue list` call per repo — bounded by the number of tracked repos
     # (typically a handful), not by issue count, so a serial loop is fine.
+    tracked_repos = {t.repo for t in tracks if t.repo}
     untracked_by_repo: dict[str, list] = {}
-    for repo in repo_to_numbers:
-        tracked = set(repo_to_numbers[repo])
+    for repo in tracked_repos:
+        tracked = set(repo_to_numbers.get(repo, []))
         open_rows = fetch_open_issues(repo)
         untracked_by_repo[repo] = [r for r in open_rows if r.get("number") not in tracked]
 
@@ -140,6 +148,22 @@ def run(args: list[str]) -> int:
             if nums:
                 hot_by_track[(t.repo, t.name)] = nums
 
+    # Shared/private tier duplicates (#361): the viewer is otherwise blind to
+    # them — discover_tracks drops the private copy with a stderr-only WARN. We
+    # surface them as a read-only health signal; `safe` mirrors dedupe-tiers'
+    # no-data-loss invariant (private issue refs ⊆ shared), so the viewer can
+    # tell auto-removable orphans from diverged ones needing manual review.
+    tier_duplicates = []
+    for shared_t, private_t in find_tier_duplicates(cfg):
+        tier_duplicates.append({
+            "repo": shared_t.repo,
+            "folder": shared_t.folder,
+            "name": shared_t.name,
+            "shared_path": str(shared_t.path),
+            "private_path": str(private_t.path),
+            "safe": issue_refs(private_t) <= issue_refs(shared_t),
+        })
+
     next_up_default = cfg.get("next_up_default")
     now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
     print(json.dumps(
@@ -148,7 +172,8 @@ def run(args: list[str]) -> int:
                      config_repos=config_repos,
                      plan_by_track=plan_by_track,
                      hot_by_track=hot_by_track,
-                     next_up_default=next_up_default),
+                     next_up_default=next_up_default,
+                     tier_duplicates=tier_duplicates),
         indent=2,
     ))
     return 0

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

@@ -9,6 +9,7 @@ Use --interactive (or -i) for the legacy blank-prompt mode where you fill in
 each section by hand.
 """
 import fnmatch
+import json
 import subprocess
 from datetime import datetime, timedelta
 
@@ -30,9 +31,10 @@ from lib.prompts import prompt_lines, parse_flags, prompt_input
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next", "--repo"})
+    flags, positional = parse_flags(args, {"--interactive", "-i", "--set-next", "--auto-next", "--suggest-next", "--repo"})
     interactive = flags.get("--interactive", False) or flags.get("-i", False)
     auto_next = flags.get("--auto-next", False)
+    suggest_next = flags.get("--suggest-next", False)
 
     # Support both --set-next=4167,4148 (parse_flags handles via key=value) and
     # --set-next 4167,4148 (space-separated). For the space form, parse_flags
@@ -80,6 +82,12 @@ def run(args: list[str]) -> int:
     if not track:
         return 1
 
+    # --suggest-next: read-only. Compute the algorithmic next_up suggestion and
+    # emit it as JSON for a non-CLI caller (the VS Code native picker, #274) to
+    # render + confirm. No prompt, no write — the caller writes via --set-next.
+    if suggest_next:
+        return _suggest_next_json(track, cfg)
+
     # Apply --set-next first if present, so derived/interactive output reflects it.
     if isinstance(set_next_raw, str):
         rc = _apply_set_next(track, set_next_raw, cfg)
@@ -129,6 +137,81 @@ def _apply_set_next(track, raw: str, cfg: dict) -> int:
     return 0
 
 
+def _compute_auto_next(track, cfg: dict):
+    """Compute the sibling-filtered next_up suggestion (read-only — no prompt,
+    no write). Shared by the interactive --auto-next flow and the --suggest-next
+    JSON output (#274).
+
+    Returns (suggestion, by_num, skipped, had_raw):
+      - suggestion: list[int] — ordered issue numbers to queue
+      - by_num: {int: issue} — fetched issues keyed by number (for decoration)
+      - skipped: list[(int, str)] — (issue, sibling_track) dropped as already-claimed
+      - had_raw: bool — whether the algorithm produced ANY candidate before the
+        sibling filter (distinguishes "no open non-blocker issues" from
+        "all candidates claimed by siblings"). Caller guarantees track.repo and a
+        non-empty issue list.
+    """
+    issue_nums = track.meta.get("github", {}).get("issues") or []
+    issues = fetch_issues(track.repo, issue_nums)
+    blocker_nums = track.meta.get("blockers") or []
+    track_milestone = track.meta.get("milestone_alignment") or None
+    hot_nums = hot_issue_numbers(track.local_path) if track.local_path else set()
+    in_progress_set = {i["number"] for i in issues if issue_in_progress(i, hot_nums)}
+    _, order = resolve_next_up_order(track.meta, cfg.get("next_up_default"))
+    raw_suggestion = suggest_next_up(
+        issues, blocker_nums,
+        track_milestone=track_milestone,
+        in_progress_nums=in_progress_set,
+        order=order,
+    )
+    claimed = _sibling_claimed_next_up_map(track, cfg)
+    suggestion, skipped = [], []
+    for num in raw_suggestion:
+        if num in claimed:
+            skipped.append((num, claimed[num]))
+        else:
+            suggestion.append(num)
+    by_num = {i["number"]: i for i in issues}
+    return suggestion, by_num, skipped, bool(raw_suggestion)
+
+
+def _suggest_next_json(track, cfg: dict) -> int:
+    """Emit the algorithmic next_up suggestion as JSON for a non-CLI caller (#274).
+
+    Read-only: never prompts or writes. Soft errors (no repo / no issues) are
+    reported in the payload with an empty `suggested`, so the caller always gets
+    parseable JSON and exit 0; hard errors (track resolution) are handled upstream
+    in run() before this is reached.
+    """
+    out = {
+        "track": track.name,
+        "repo": track.repo,
+        "current": track.meta.get("next_up") or [],
+        "suggested": [],
+        "skipped": [],
+    }
+    if not track.repo:
+        out["error"] = f"track '{track.name}' has no github.repo"
+        print(json.dumps(out))
+        return 0
+    if not (track.meta.get("github", {}).get("issues") or []):
+        out["error"] = f"no issues attached to '{track.name}'"
+        print(json.dumps(out))
+        return 0
+    suggestion, by_num, skipped, _ = _compute_auto_next(track, cfg)
+    for num in suggestion:
+        i = by_num.get(num, {})
+        out["suggested"].append({
+            "number": num,
+            "title": i.get("title", ""),
+            "priority": extract_priority(i.get("labels", [])),
+            "milestone": short_milestone(i.get("milestone")) or "",
+        })
+    out["skipped"] = [{"number": n, "claimed_by": s} for n, s in skipped]
+    print(json.dumps(out))
+    return 0
+
+
 def _apply_auto_next(track, cfg: dict) -> int:
     """Suggest a next_up list from open issues; prompt user to apply/edit/skip.
 
@@ -150,38 +233,19 @@ def _apply_auto_next(track, cfg: dict) -> int:
         print(f"No issues attached to {track.name}; nothing to suggest.")
         return 0
 
-    issues = fetch_issues(track.repo, issue_nums)
-    blocker_nums = track.meta.get("blockers") or []
-    track_milestone = track.meta.get("milestone_alignment") or None
-    hot_nums = hot_issue_numbers(track.local_path) if track.local_path else set()
-    in_progress_set = {i["number"] for i in issues if issue_in_progress(i, hot_nums)}
-    _, order = resolve_next_up_order(track.meta, cfg.get("next_up_default"))
-    raw_suggestion = suggest_next_up(
-        issues, blocker_nums,
-        track_milestone=track_milestone,
-        in_progress_nums=in_progress_set,
-        order=order,
-    )
-    if not raw_suggestion:
+    suggestion, by_num, skipped, had_raw = _compute_auto_next(track, cfg)
+    # Print one line per sibling-claimed skip so the user knows what was dropped.
+    for num, sib in skipped:
+        print(f"↷ skipped #{num} (already next_up on '{sib}')")
+
+    if not had_raw:
         print(f"No open, non-blocker issues for {track.name}; next_up unchanged.")
         return 0
-
-    # Filter sibling-claimed issues out of the suggestion. Print one line
-    # per skip so the user knows what was dropped and why.
-    claimed = _sibling_claimed_next_up_map(track, cfg)
-    suggestion = []
-    for num in raw_suggestion:
-        if num in claimed:
-            print(f"↷ skipped #{num} (already next_up on '{claimed[num]}')")
-        else:
-            suggestion.append(num)
-
     if not suggestion:
         print(f"All suggested issues are already next_up on sibling tracks; next_up unchanged.")
         return 0
 
     # Decorate with title + priority + milestone for the preview.
-    by_num = {i["number"]: i for i in issues}
     print(f"\nSuggested next_up for {track.name}:")
     for num in suggestion:
         i = by_num.get(num, {})

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

@@ -3,11 +3,15 @@
 Runs in sequence:
   1. refresh-md --all --yes  (drift in body status tables)
   2. reconcile --all          (sync track/<slug> labels ↔ frontmatter)
-  3. duplicates               (find consolidation candidates)
+  3. dedupe-tiers             (report shared/private duplicate tracks)
+  4. duplicates               (find consolidation candidates)
 
 One command for the standard weekly maintenance pass.
 
-Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 3 (duplicates)
+Step 3 (dedupe-tiers) is report-only here — it never deletes during hygiene.
+Run `/work-plan dedupe-tiers --apply` directly to remove the safe orphans.
+
+Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 4 (duplicates)
 is per-repo, so:
   - when --repo is set, it's scoped to that repo;
   - when --repo is absent and config has exactly one repo, it runs against
@@ -18,7 +22,7 @@ is per-repo, so:
 Pass --timeout=N to set the gh subprocess timeout for the duplicates step
 (default 30s).
 """
-from commands import refresh_md, reconcile, duplicates
+from commands import refresh_md, reconcile, duplicates, dedupe_tiers
 from lib.config import load_config, ConfigError
 from lib.prompts import parse_flags
 import time
@@ -62,7 +66,7 @@ def run(args: list[str]) -> int:
 
     t0 = time.time()
     print("=" * 60)
-    print(f"WEEKLY HYGIENE — step 1 of 3: refresh-md{scope_label}")
+    print(f"WEEKLY HYGIENE — step 1 of 4: refresh-md{scope_label}")
     print("=" * 60)
     refresh_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
     if yes:
@@ -70,12 +74,12 @@ def run(args: list[str]) -> int:
     rc = refresh_md.run(refresh_args)
     if rc != 0:
         print(f"\n⚠ refresh-md exited with code {rc}; continuing.")
-    print(f"  (step 1/3 done in {time.time() - t0:.1f}s)")
+    print(f"  (step 1/4 done in {time.time() - t0:.1f}s)")
 
     t1 = time.time()
     print()
     print("=" * 60)
-    print(f"WEEKLY HYGIENE — step 2 of 3: reconcile{scope_label}")
+    print(f"WEEKLY HYGIENE — step 2 of 4: reconcile{scope_label}")
     print("=" * 60)
     reconcile_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
     if yes:
@@ -83,7 +87,18 @@ def run(args: list[str]) -> int:
     rc = reconcile.run(reconcile_args)
     if rc != 0:
         print(f"\n⚠ reconcile exited with code {rc}; continuing.")
-    print(f"  (step 2/3 done in {time.time() - t1:.1f}s)")
+    print(f"  (step 2/4 done in {time.time() - t1:.1f}s)")
+
+    t_dt = time.time()
+    print()
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 3 of 4: dedupe-tiers{scope_label} (report-only)")
+    print("=" * 60)
+    dedupe_args = [f"--repo={repo_key}"] if repo_key else []
+    rc = dedupe_tiers.run(dedupe_args)
+    if rc != 0:
+        print(f"\n⚠ dedupe-tiers exited with code {rc}; continuing.")
+    print(f"  (step 3/4 done in {time.time() - t_dt:.1f}s)")
 
     if skip_dups:
         print()
@@ -93,7 +108,7 @@ def run(args: list[str]) -> int:
     t2 = time.time()
     print()
     print("=" * 60)
-    print("WEEKLY HYGIENE — step 3 of 3: duplicates")
+    print("WEEKLY HYGIENE — step 4 of 4: duplicates")
     print("=" * 60)
 
     try:
@@ -122,7 +137,7 @@ def run(args: list[str]) -> int:
     rc = duplicates.run(dupes_args)
     if rc != 0:
         print(f"\n⚠ duplicates exited with code {rc}.")
-    print(f"  (step 3/3 done in {time.time() - t2:.1f}s)")
+    print(f"  (step 4/4 done in {time.time() - t2:.1f}s)")
 
     print()
     print(f"✓ Weekly hygiene complete ({time.time() - t0:.1f}s total). Review the duplicate candidates above and "