@stylusnexus/work-plan 2026.6.15 → 2026.6.18-1

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,27 +510,29 @@ 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). |
+| `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), `--expect=<fp>` (compare-and-swap: the fingerprint of the track's issue list as the caller last saw it — if the on-disk list changed since, the write aborts with a `{stale}` JSON signal instead of clobbering; used by the viewer's assisted-slot flow, #241). The write always re-reads the file and merges onto fresh disk; for a shared-tier track on a `plan_branch` it fetch+rebases the worktree first and aborts with `{needs_rebase}` on an un-rebasable divergence. |
 | `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. |
 | `plan-branch <init\|status\|push> <repo> [--branch=<name>] [--confirm=<token>] [--dry-run] [--json]` | Set up and share a repo's canonical **shared-tier** plan branch. The `.work-plan/` tier is pinned to ONE per-repo `plan_branch`, read/written through a dedicated git worktree, so planning never diverges across code branches or pollutes PR / deploy diffs. `init` creates that branch + a `.work-plan/` skeleton (default an **orphan** `work-plan/plan` — zero shared history with code, like `gh-pages`; override with `--branch`) and records `plan_branch` in config — or **connects** to a teammate's already-published branch if one exists. `init` is **local only** (no push). `status` reports whether the branch exists, is published to origin, and how many commits are unpushed (`--json` for the machine shape). `push` shares it: on a **public** repo it prints a confirm heads-up + token and exits (re-run with `--confirm=<token>`); `--dry-run` previews the commits that would push. Requires a repo registered via `init-repo` with a local clone path. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
 | `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
-| `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
+| `auto-triage [--repo=<key>] [--apply] [--json] [--heuristic] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`); the scan stamps a `batch_id` and writes a per-repo cache file. `--json` emits the batch (+ prompt + answers path) as one JSON object on stdout for the VS Code viewer's Suggested bucket (#241) instead of the human prompt. `--heuristic` (#373) skips the LLM: it scores each issue against the candidate tracks with local signals (milestone match, track-label overlap, title/scope keyword overlap) and writes the v2 answers file itself (`source: "heuristic"`, abstain-first) — so suggestions work with no Claude session (lower-trust, offline). `--apply` accepts the **v2** abstain-first answers shape (`{version,batch_id,suggestions:[{issue,verdict,track,confidence,margin,rationale}]}` — only clear-margin `suggest` verdicts are slotted; abstains/narrow stay untracked) as well as the legacy v1 `[{track,issues}]`. Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
 | `coverage [--repo=<key>] [--list] [--limit=N]` | Report how many open issues are not in any track. `--list` prints titles. Read-only. |
 | `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft] [--yes]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). In an `--all`/`--repo` sweep it also detects **MOVEs** — an issue relabeled from one track to another in the same repo is moved (removed from the old track, added to the new); ambiguous targets stay as FLAGs. `--draft` previews the label drift (ADDs/MOVEs/FLAGs) without prompting or writing. `--yes` applies without prompting (non-interactive, e.g. the VS Code extension); PUBLIC-repo move destinations are skipped under `--yes`. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |

package/VERSION

@@ -1 +1 @@
-2026.06.15+d52d670
+2026.06.18+d4980a1

package/package.json

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

@@ -75,6 +75,8 @@ All three follow the same pattern:
 
 Show the proposed labels/clusters/assignments BEFORE applying. The user may want to override.
 
+**`auto-triage` answers — write atomically and copy the `batch_id`.** The VS Code viewer watches the answers file and reads suggestions live (#241), so a half-written file would be read mid-write. Write to a `.tmp` sibling and then rename it onto the final `auto_triage.<repo>.answers.json` path the CLI printed (the Write tool's create-then-replace is fine; never append). Use the **v2** answers shape — `{"version": 2, "batch_id": "<copy from the scan output>", "suggestions": [...]}` — and copy the `batch_id` the scan printed so the viewer can tell fresh suggestions from a stale older scan. Prefer `"verdict": "abstain"` for issues with no clear home: most untracked issues genuinely have none, and a wrong suggestion a human rubber-stamps is worse than silence.
+
 **Which one to use:**
 - `group` — issues need to be *clustered into new track files* (run once per milestone or after a re-org)
 - `auto-triage` — untracked issues need to be *assigned to existing tracks* (run after `coverage` shows a gap)

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

@@ -9,14 +9,30 @@ Two-step (same pattern as `group`):
 Use --repo=<key> to scope to one configured repo. When the config has a
 single repo, --repo is inferred automatically.
 
-Answers JSON format (written to cache/auto_triage.answers.json):
-  [
-    {"track": "auth-flow", "issues": [4501, 4502]},
-    {"track": "tabletop-sessions", "issues": [4503]}
-  ]
-Issues omitted from every list are left untracked (no error).
+Answers JSON — two accepted shapes (the reader sniffs which one):
+
+  v1 (legacy, still accepted):
+    [
+      {"track": "auth-flow", "issues": [4501, 4502]},
+      {"track": "tabletop-sessions", "issues": [4503]}
+    ]
+
+  v2 (preferred — abstain-first, per-issue, carries confidence/rationale the
+  VS Code viewer renders; #241):
+    {"version": 2, "batch_id": "<from the batch file>", "suggestions": [
+      {"issue": 4501, "verdict": "suggest", "track": "auth-flow",
+       "runner_up": "tabletop-sessions", "confidence": 0.82, "margin": "clear",
+       "rationale": "shares milestone v0.4.0 and label area/auth"},
+      {"issue": 4507, "verdict": "abstain", "rationale": "no track covers billing"}
+    ]}
+
+In v2 `--apply` slots only verdict=="suggest" assignments whose margin is "clear"
+(narrow-margin / abstained issues stay untracked — the safe default). Issues
+omitted entirely are left untracked (no error).
 """
+import hashlib
 import json
+import os
 import subprocess
 import sys
 from datetime import datetime
@@ -29,36 +45,62 @@ from lib.tracks import discover_tracks
 from lib.github_state import fetch_open_issues
 
 
-def _batch_path() -> Path:
-    return cache_dir() / "auto_triage.json"
+def _repo_slug(repo) -> str:
+    """Filesystem-safe slug for a repo's per-repo cache files (#241): two repos
+    never collide on the single fixed cache path (a multi-repo clobber race)."""
+    return (repo or "").replace("/", "_")
 
 
-def _answers_path() -> Path:
-    return cache_dir() / "auto_triage.answers.json"
+def _batch_path(repo=None) -> Path:
+    name = f"auto_triage.{_repo_slug(repo)}.json" if repo else "auto_triage.json"
+    return cache_dir() / name
 
 
-PROMPT_TEMPLATE = """\
-You have a list of EXISTING tracks and a list of UNTRACKED open issues.
-Assign each issue to the most appropriate existing track.
+def _answers_path(repo=None) -> Path:
+    name = f"auto_triage.{_repo_slug(repo)}.answers.json" if repo else "auto_triage.answers.json"
+    return cache_dir() / name
 
-Return JSON — an array of assignment objects:
-[
-  {"track": "<exact-track-slug>", "issues": [<issue-numbers>]},
-  ...
-]
+
+def _make_batch_id(repo: str) -> str:
+    """A short id correlating an answers file to the batch that produced it. The
+    viewer checks it so a stale answers file from an older scan isn't rendered as
+    current (mtime alone can't tell — answers are always newer than the batch)."""
+    stamp = datetime.now().strftime("%Y%m%dT%H%M%S")
+    return hashlib.sha256(f"{repo}:{stamp}".encode("utf-8")).hexdigest()[:12]
+
+
+PROMPT_TEMPLATE = """\
+For EACH untracked issue below, decide whether one of the EXISTING tracks is a
+clearly correct home — and if not, ABSTAIN. Most untracked issues will NOT have
+a clear home; that is normal and correct. Only suggest a track when the issue is
+unmistakably about that track's scope.
+
+Return JSON in this exact shape:
+{"version": 2, "batch_id": "<copy the batch_id printed below>", "suggestions": [
+  {"issue": <num>, "verdict": "suggest", "track": "<exact-track-slug>",
+   "runner_up": "<second-best slug or null>", "confidence": <0.0-1.0>,
+   "margin": "clear" | "narrow",
+   "rationale": "<the concrete shared signal: a label, milestone, or scope keyword>"},
+  {"issue": <num>, "verdict": "abstain", "rationale": "<why no track fits>"}
+]}
 
 Rules:
 - Use ONLY the track slugs listed under "Existing tracks" below.
-- An issue can appear in AT MOST ONE track assignment.
-- Omit issues that genuinely don't fit any existing track (they stay untracked).
+- Name your top choice AND your runner-up. If you cannot clearly distinguish
+  them, set "margin": "narrow" — that means neither is clearly right.
+- "rationale" must cite a CONCRETE shared signal (a label, a milestone, a scope
+  keyword). "Generally related" is not a valid reason — abstain instead.
+- When in doubt, ABSTAIN (verdict "abstain", no track). A wrong suggestion a
+  human rubber-stamps is worse than no suggestion.
 - Do NOT invent new tracks — that's /work-plan group's job.
-- Do NOT include empty assignments (issues: []).
 
 """
 
 
 def run(args: list[str]) -> int:
     apply_mode = "--apply" in args
+    heuristic = "--heuristic" in args
+    json_mode = "--json" in args
     repo_arg = next((a for a in args if a.startswith("--repo=")), None)
 
     limit = 100
@@ -77,7 +119,13 @@ def run(args: list[str]) -> int:
         return 1
 
     if apply_mode:
-        return _apply(cfg)
+        # Resolve repo for per-repo cache files; no --repo falls back to the
+        # legacy fixed filenames (back-compat with the pre-#241 terminal flow).
+        apply_repo = None
+        if repo_arg:
+            folder = repo_arg.split("=", 1)[1]
+            apply_repo = cfg.get("repos", {}).get(folder, {}).get("github")
+        return _apply(cfg, apply_repo)
 
     # -----------------------------------------------------------------------
     # Step 1: fetch untracked issues + print AI prompt
@@ -106,7 +154,14 @@ def run(args: list[str]) -> int:
         and t.meta.get("status") in ("active", "in-progress", "blocked")
     ]
     if not active_tracks:
-        print(f"No active tracks found for {repo}. Run /work-plan group first.")
+        # --json callers (the VS Code viewer) parse stdout as JSON, so this
+        # informational early-exit must stay machine-readable rather than a bare
+        # human line (which crashed Suggest Tracks with a JSON parse error).
+        if json_mode:
+            print(json.dumps({"repo": repo, "folder": folder,
+                              "tracks": [], "untracked": [], "note": "no_active_tracks"}))
+        else:
+            print(f"No active tracks found for {repo}. Run /work-plan group first.")
         return 0
 
     # Build per-repo set of already-tracked issue numbers
@@ -115,36 +170,82 @@ def run(args: list[str]) -> int:
         if t.repo == repo and t.has_frontmatter:
             tracked_nums.update(t.meta.get("github", {}).get("issues") or [])
 
-    print(f"Fetching open issues from {repo}...")
+    # Progress goes to stderr so --json keeps stdout a single clean JSON object.
+    print(f"Fetching open issues from {repo}...", file=sys.stderr)
     open_issues = fetch_open_issues(repo, limit=500)
     untracked = [i for i in open_issues if i.get("number") not in tracked_nums]
 
     if not untracked:
-        print(f"No untracked issues found for {repo} — full coverage!")
+        if json_mode:
+            print(json.dumps({"repo": repo, "folder": folder,
+                              "tracks": [], "untracked": [], "note": "full_coverage"}))
+        else:
+            print(f"No untracked issues found for {repo} — full coverage!")
         return 0
 
-    batch_path = _batch_path()
-    batch_path.write_text(json.dumps({
+    batch_id = _make_batch_id(repo)
+    batch_obj = {
+        "batch_id": batch_id,
         "repo": repo,
         "folder": folder,
         "untracked": untracked,
         "tracks": [{"slug": t.meta.get("track", t.name), "name": t.name,
                     "milestone": t.meta.get("milestone_alignment"),
-                    "priority": t.meta.get("launch_priority")}
+                    "priority": t.meta.get("launch_priority"),
+                    # Scope/description grounds the match on what the track is
+                    # FOR, not just its slug string (#241, ai-engineer review).
+                    "scope": t.meta.get("scope") or t.meta.get("description") or ""}
                    for t in active_tracks],
-    }, indent=2))
+    }
+    batch_path = _batch_path(repo)
+    batch_path.write_text(json.dumps(batch_obj, indent=2))
+
+    # --heuristic (#373): compute suggestions deterministically (no LLM) and
+    # write the v2 answers file ourselves, so the Suggested bucket works with no
+    # Claude session. Same schema the LLM path produces, stamped
+    # source:"heuristic" so the viewer can flag it lower-trust. Atomic
+    # (.tmp + os.replace) since the viewer watches this path live.
+    if heuristic:
+        from lib.heuristic_triage import score_suggestions
+        suggestions = score_suggestions(
+            untracked,
+            [{"slug": t.meta.get("track", t.name), "name": t.name,
+              "milestone": t.meta.get("milestone_alignment"),
+              "scope": t.meta.get("scope") or t.meta.get("description") or "",
+              "labels": (t.meta.get("github", {}) or {}).get("labels") or []}
+             for t in active_tracks],
+        )
+        answers_path = _answers_path(repo)
+        tmp = answers_path.with_suffix(answers_path.suffix + ".tmp")
+        tmp.write_text(json.dumps(
+            {"version": 2, "source": "heuristic", "batch_id": batch_id,
+             "suggestions": suggestions}, indent=2))
+        os.replace(tmp, answers_path)
+
+    # --json: emit the batch (+ prompt + answers path) as one machine-readable
+    # object for the VS Code viewer, which captures batch_id to correlate the
+    # answers a Claude session writes back (#241). No human prose on stdout.
+    if "--json" in args:
+        print(json.dumps({**batch_obj,
+                          "prompt": PROMPT_TEMPLATE,
+                          "answers_path": str(_answers_path(repo))}))
+        return 0
 
     print(f"Found {len(untracked)} untracked issues ({len(active_tracks)} active tracks).")
     print()
     print("=" * 60)
     print(PROMPT_TEMPLATE)
 
+    print(f"batch_id: {batch_id}  (copy into the answers JSON)")
+    print()
     print("Existing tracks:")
     for t in active_tracks:
         slug = t.meta.get("track", t.name)
         milestone = t.meta.get("milestone_alignment", "—")
         priority = t.meta.get("launch_priority", "—")
-        print(f"  {slug}  [{priority}, {milestone}]")
+        scope = t.meta.get("scope") or t.meta.get("description") or ""
+        scope_txt = f" — {scope}" if scope else ""
+        print(f"  {slug}  [{priority}, {milestone}]{scope_txt}")
 
     print()
     print("Untracked issues to assign:")
@@ -162,16 +263,75 @@ def run(args: list[str]) -> int:
 
     print("=" * 60)
     print()
-    print(f"After the agent returns assignment JSON, save it to:")
-    print(f"  {_answers_path()}")
+    if heuristic:
+        print(f"Heuristic suggestions written to:")
+        print(f"  {_answers_path(repo)}")
+        print("They appear in the VS Code Suggested bucket, or apply from the terminal:")
+        print(f"  python3 ~/.claude/skills/work-plan/work_plan.py auto-triage --apply --repo={folder}")
+        return 0
+    print(f"After the agent returns assignment JSON, save it (atomically — write")
+    print(f"a .tmp then rename) to:")
+    print(f"  {_answers_path(repo)}")
     print("Then run:")
-    print("  python3 ~/.claude/skills/work-plan/work_plan.py auto-triage --apply")
+    print(f"  python3 ~/.claude/skills/work-plan/work_plan.py auto-triage --apply --repo={folder}")
     return 0
 
 
-def _apply(cfg: dict) -> int:
-    answers_path = _answers_path()
-    batch_path = _batch_path()
+def _normalize_answers(answers, batch_id=None):
+    """Collapse either answers shape into v1 assignment objects [{track, issues}].
+
+    - v2 (dict with "suggestions"): keep only verdict=="suggest" whose margin is
+      not "narrow" (abstains and narrow-margin items stay untracked — the safe
+      default), group by track. confidence/rationale are for the viewer; the
+      write ignores them.
+    - v1 (list): passed through.
+
+    The file is model-authored/untrusted, so every field is hardened: issue
+    numbers int-coerced, malformed entries skipped, unknown shapes ignored.
+    Returns (assignments, batch_mismatch: bool).
+    """
+    mismatch = False
+    if isinstance(answers, dict) and "suggestions" in answers:
+        if batch_id and answers.get("batch_id") and answers["batch_id"] != batch_id:
+            mismatch = True
+        by_track: dict = {}
+        for s in answers.get("suggestions") or []:
+            if not isinstance(s, dict):
+                continue
+            if s.get("verdict") != "suggest":
+                continue
+            if s.get("margin") == "narrow":
+                continue
+            slug = (s.get("track") or "").strip()
+            if not slug:
+                continue
+            try:
+                num = int(s.get("issue"))
+            except (TypeError, ValueError):
+                continue
+            by_track.setdefault(slug, []).append(num)
+        return ([{"track": k, "issues": v} for k, v in by_track.items()], mismatch)
+
+    # v1 legacy list.
+    out = []
+    for a in answers if isinstance(answers, list) else []:
+        if not isinstance(a, dict):
+            continue
+        slug = (a.get("track") or "").strip()
+        nums = []
+        for n in a.get("issues") or []:
+            try:
+                nums.append(int(n))
+            except (TypeError, ValueError):
+                continue
+        if slug and nums:
+            out.append({"track": slug, "issues": nums})
+    return (out, mismatch)
+
+
+def _apply(cfg: dict, repo: str = None) -> int:
+    answers_path = _answers_path(repo)
+    batch_path = _batch_path(repo)
     if not answers_path.exists():
         print(f"ERROR: {answers_path} not found. Run without --apply first.")
         return 1
@@ -186,7 +346,11 @@ def _apply(cfg: dict) -> int:
         print(f"ERROR: batch folder '{folder}' not in config.yml repos.")
         return 1
 
-    answers = json.loads(answers_path.read_text())
+    raw_answers = json.loads(answers_path.read_text())
+    answers, batch_mismatch = _normalize_answers(raw_answers, batch.get("batch_id"))
+    if batch_mismatch:
+        print("⚠  answers batch_id does not match the current batch — these "
+              "suggestions may be from an older scan. Re-run without --apply to refresh.")
 
     tracks = discover_tracks(cfg)
     tracks_by_slug = {}

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

@@ -1,10 +1,11 @@
 """batch-slot subcommand — slot multiple issues into a track at once."""
 import json
 import subprocess
+import sys
 
 from lib.config import load_config, ConfigError
 from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
-from lib.frontmatter import write_file
+from lib.membership_guard import guarded_membership_write, shared_rebase_guard
 from lib.write_guard import needs_confirm, make_token, valid_token
 from lib.prompts import parse_flags
 
@@ -25,7 +26,7 @@ def _find_prior_owners(issue_num: int, repo: str, target_name: str, tracks):
 
 def run(args: list[str]) -> int:
     flags, positional = parse_flags(
-        args, {"--confirm", "--move", "--no-move", "--repo"}
+        args, {"--confirm", "--move", "--no-move", "--repo", "--expect"}
     )
 
     if len(positional) < 2:
@@ -99,8 +100,22 @@ def run(args: list[str]) -> int:
         )
         return 0
 
+    # Shared-tier rebase (#241): pull + rebase the plan_branch worktree onto
+    # origin before writing; an un-rebasable divergence aborts cleanly.
+    ok, reason = shared_rebase_guard(target, cfg)
+    if not ok:
+        print(json.dumps({"needs_rebase": True, "reason": reason, "track": target.name}))
+        return 0
+
     do_move = "--move" in flags
 
+    # --expect=<fp> opts into the compare-and-swap staleness guard (#241). When
+    # present (the assisted/viewer path) advisory notes go to stderr so stdout
+    # stays pure for the {stale} abort signal the caller parses.
+    expect = flags.get("--expect")
+    expect = expect if isinstance(expect, str) else None
+    notes = sys.stderr if expect is not None else sys.stdout
+
     # Collect source tracks that need issue removal (consolidated per source).
     source_removals: dict[str, tuple] = {}  # source_name -> (source_track, set[issue_num])
 
@@ -113,24 +128,29 @@ def run(args: list[str]) -> int:
             skipped.append(issue_num)
             continue
 
-        # Milestone mismatch check (non-blocking warning).
-        proc = subprocess.run(
-            ["gh", "issue", "view", str(issue_num),
-             "--repo", target.repo, "--json", "milestone"],
-            capture_output=True, text=True,
-        )
-        if proc.returncode == 0:
-            info = json.loads(proc.stdout)
-            m = info.get("milestone", {})
-            if (
-                m and m.get("title")
-                and m["title"] != target.meta.get("milestone_alignment")
-            ):
-                print(
-                    f"⚠  #{issue_num} is on milestone '{m['title']}', "
-                    f"track '{target.name}' aligned to"
-                    f" '{target.meta.get('milestone_alignment')}'."
-                )
+        # Milestone mismatch check (non-blocking warning). Never let gh being
+        # absent/odd crash the command — it's advisory and sits before the write.
+        try:
+            proc = subprocess.run(
+                ["gh", "issue", "view", str(issue_num),
+                 "--repo", target.repo, "--json", "milestone"],
+                capture_output=True, text=True,
+            )
+            if proc.returncode == 0:
+                info = json.loads(proc.stdout)
+                m = info.get("milestone", {})
+                if (
+                    m and m.get("title")
+                    and m["title"] != target.meta.get("milestone_alignment")
+                ):
+                    print(
+                        f"⚠  #{issue_num} is on milestone '{m['title']}', "
+                        f"track '{target.name}' aligned to"
+                        f" '{target.meta.get('milestone_alignment')}'.",
+                        file=notes,
+                    )
+        except (OSError, json.JSONDecodeError):
+            pass
 
         # Prior-owner detection.
         sources = _find_prior_owners(
@@ -149,7 +169,8 @@ def run(args: list[str]) -> int:
             names = ", ".join(f"'{t.name}'" for t in sources)
             print(
                 f"ℹ #{issue_num} still listed in {names}"
-                f" — re-run with --move to relocate."
+                f" — re-run with --move to relocate.",
+                file=notes,
             )
 
     if not slotted:
@@ -160,21 +181,25 @@ def run(args: list[str]) -> int:
             )
         return 0
 
-    # Write source tracks (consolidated removals).
+    # Write source tracks (consolidated removals), each re-read + merged onto
+    # fresh disk so a concurrent edit to a source track isn't clobbered.
     if do_move:
         for src_name, (src, removals) in source_removals.items():
-            src_issues = [
-                n for n in (src.meta.get("github", {}).get("issues") or [])
-                if n not in removals
-            ]
-            src.meta.setdefault("github", {})["issues"] = src_issues
-            write_file(src.path, src.meta, src.body)
+            guarded_membership_write(src.path, remove_nums=removals)
             removed_str = ", ".join(f"#{n}" for n in sorted(removals))
-            print(f"  ✓ Removed {removed_str} from '{src_name}'.")
-
-    # Write target track once.
-    target.meta.setdefault("github", {})["issues"] = sorted(issues)
-    write_file(target.path, target.meta, target.body)
+            print(f"  ✓ Removed {removed_str} from '{src_name}'.", file=notes)
+
+    # Write target track once. Carries `expect`: on a detected concurrent change
+    # to the membership list it aborts with {stale} instead of clobbering.
+    result = guarded_membership_write(target.path, add_nums=slotted, expect=expect)
+    if result.get("stale"):
+        print(json.dumps({
+            "stale": True,
+            "reason": result["reason"],
+            "current": result["current"],
+            "track": target.name,
+        }))
+        return 0
 
     slotted_str = ", ".join(f"#{n}" for n in slotted)
     print(f"✓ Slotted {slotted_str} into '{target.name}'.")