@stylusnexus/work-plan 2026.6.16 → 2026.6.18

package/README.md

@@ -514,7 +514,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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` + `dedupe-tiers` (report-only) + `duplicates`. With `--repo=<key>`, steps 1–3 scope to that repo and the global `duplicates` step is skipped. |
@@ -532,7 +532,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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.16+ebd6045
+2026.06.18+64ae461

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.16",
+  "version": "2026.6.18",
   "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"

package/skills/work-plan/SKILL.md

@@ -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,61 @@ 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
     repo_arg = next((a for a in args if a.startswith("--repo=")), None)
 
     limit = 100
@@ -77,7 +118,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
@@ -115,7 +162,8 @@ 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]
 
@@ -123,28 +171,69 @@ def run(args: list[str]) -> int:
         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 +251,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 +334,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}'.")

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

@@ -1,10 +1,11 @@
 """slot subcommand."""
 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, prompt_input
 
@@ -28,7 +29,7 @@ def run(args: list[str]) -> int:
     # --confirm uses equals form: --confirm=<token>
     # --move / --no-move are bare flags
     # --repo uses equals form: --repo=<key>
-    flags, positional = parse_flags(args, {"--confirm", "--move", "--no-move", "--repo"})
+    flags, positional = parse_flags(args, {"--confirm", "--move", "--no-move", "--repo", "--expect"})
     if not positional:
         print("usage: work_plan.py slot <issue-num> [track | track@repo] [--repo=<key>]")
         return 2
@@ -116,39 +117,67 @@ def run(args: list[str]) -> int:
         }))
         return 0
 
+    # Shared-tier rebase (#241): for a track pinned to a plan_branch, pull +
+    # rebase the worktree onto origin before writing so a teammate's pushed plan
+    # change isn't clobbered. A divergence we can't auto-rebase 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
+
     # Determine move behavior from flags.
     # --move: remove issue from prior owners.
     # Default / --no-move: add-only; print a note naming prior owners.
     do_move = "--move" in flags
 
-    sources = _find_prior_owners(issue_num, target.repo, target.name, tracks)
+    # --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
 
-    issues.append(issue_num)
-    target.meta.setdefault("github", {})["issues"] = sorted(issues)
-
-    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 '{target.meta.get('milestone_alignment')}'.")
+    sources = _find_prior_owners(issue_num, target.repo, target.name, tracks)
 
+    # Milestone mismatch is advisory only — never let gh being absent/odd crash
+    # the command (it sits between the rebase guard and 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 '{target.meta.get('milestone_alignment')}'.",
+                      file=notes)
+    except (OSError, json.JSONDecodeError):
+        pass
+
+    # Move sources first (each re-read + merged onto fresh disk), then the
+    # target. The target write carries `expect`: on a detected concurrent change
+    # to the membership list it aborts with {stale} instead of clobbering.
     if sources and do_move:
         for src in sources:
-            src_issues = [n for n in (src.meta.get("github", {}).get("issues") or [])
-                          if n != issue_num]
-            src.meta.setdefault("github", {})["issues"] = src_issues
-            write_file(src.path, src.meta, src.body)
-            print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+            guarded_membership_write(src.path, remove_nums=[issue_num])
+            print(f"  ✓ Removed #{issue_num} from '{src.name}'.", file=notes)
     elif sources and not do_move:
         names = ", ".join(f"'{t.name}'" for t in sources)
-        print(f"ℹ #{issue_num} still listed in {names} — re-run with --move to relocate.")
+        print(f"ℹ #{issue_num} still listed in {names} — re-run with --move to relocate.",
+              file=notes)
+
+    result = guarded_membership_write(target.path, add_nums=[issue_num], expect=expect)
+    if result.get("stale"):
+        print(json.dumps({
+            "stale": True,
+            "reason": result["reason"],
+            "current": result["current"],
+            "track": target.name,
+        }))
+        return 0
 
-    write_file(target.path, target.meta, target.body)
     print(f"✓ Slotted #{issue_num} into '{target.name}'.")
     return 0