@stylusnexus/work-plan 2026.6.15 → 2026.6.18

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

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

@@ -0,0 +1,52 @@
+"""which-repo — resolve the current directory to a configured repo.
+
+Prints the matched repo's config key + GitHub slug, or reports no match. The
+VS Code viewer spawns this with cwd set to the workspace folder to auto-focus its
+repo lens (#357); `brief` calls the underlying resolver directly for cwd
+auto-scope (#358). Read-only — never mutates anything.
+
+Exit codes (human form): 0 on a match, 1 on no match — so a shell caller can
+gate on it. The `--json` form always exits 0 and prints a `{"key": ...}` payload
+(key is null on no match) for the viewer to parse.
+"""
+import json
+import os
+
+from lib.config import load_config, ConfigError
+from lib.cwd_repo import resolve_repo_for_dir
+from lib.prompts import parse_flags
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, {"--json"})
+    want_json = bool(flags.get("--json"))
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        if want_json:
+            print(json.dumps({"key": None}))
+            return 0
+        print(f"ERROR: {e}")
+        return 1
+
+    match = resolve_repo_for_dir(cfg, os.getcwd())
+
+    if want_json:
+        if match:
+            print(json.dumps({
+                "key": match["key"],
+                "github": match.get("github"),
+                "matched_by": match["matched_by"],
+            }))
+        else:
+            print(json.dumps({"key": None}))
+        return 0
+
+    if match:
+        how = "local clone path" if match["matched_by"] == "local" else "git remote"
+        print(f"Resolved to repo '{match['key']}' (matched by {how}).")
+        return 0
+
+    print("No configured repo matches the current directory.")
+    return 1

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

@@ -0,0 +1,133 @@
+"""Resolve a directory to a configured repo (config key + GitHub slug).
+
+Shared substrate for two sibling features: `brief` cwd auto-scope (#358) and the
+VS Code viewer auto-focus (#357). Both need the same "which configured repo is
+this directory?" answer, so it lives here once — exposed to the viewer through
+the `which-repo` command and called directly by `brief`.
+
+Resolution order: the local clone path is the primary signal (it's the most
+explicit thing the user configured); the git `origin` remote is the fallback for
+repos registered with `local: null`. If both resolve but to different keys (which
+shouldn't happen in practice), the local-path key wins.
+
+Read-only and never raises — every git call goes through the bounded `_git`
+wrapper, which returns None on failure, and a no-match returns None so callers
+fall back to their current all-repos behavior unchanged.
+"""
+import re
+from pathlib import Path
+from typing import Optional
+
+from lib.git_state import _git
+
+
+def _normalize_remote_url(url: str) -> Optional[str]:
+    """Normalize a git remote URL to a lowercased `org/repo` slug, or None.
+
+    Handles the forms git emits for GitHub remotes:
+      git@github.com:org/repo.git        -> org/repo   (scp-like)
+      ssh://git@github.com/org/repo.git  -> org/repo
+      https://github.com/org/repo.git    -> org/repo
+      https://github.com/org/repo        -> org/repo
+
+    A trailing `.git`, surrounding whitespace, and trailing slashes are stripped.
+    Returns None for anything it can't parse into a host-path.
+    """
+    if not url:
+        return None
+    u = url.strip()
+
+    # scp-like syntax: [user@]host:path  (no scheme, single colon before path)
+    m = re.match(r"^[\w.+-]+@[\w.-]+:(.+)$", u)
+    if m:
+        path = m.group(1)
+    else:
+        # url syntax: scheme://[user@]host[:port]/path
+        m = re.match(r"^[\w.+-]+://(?:[^/@]+@)?[^/]+/(.+)$", u)
+        if not m:
+            return None
+        path = m.group(1)
+
+    path = path.strip().strip("/")
+    if path.endswith(".git"):
+        path = path[:-len(".git")]
+    path = path.strip("/")
+    return path.lower() or None
+
+
+def _toplevel(start_dir) -> Optional[Path]:
+    """The git work-tree root containing `start_dir`, resolved absolute, or None.
+
+    Uses `rev-parse --show-toplevel` (not the raw dir) so resolution works from
+    any nested subdirectory and a configured `local` that merely *contains* the
+    cwd can't false-match.
+    """
+    proc = _git(start_dir, "rev-parse", "--show-toplevel")
+    if proc is None or proc.returncode != 0:
+        return None
+    out = proc.stdout.strip()
+    if not out:
+        return None
+    try:
+        return Path(out).resolve()
+    except OSError:
+        return None
+
+
+def _origin_slug(start_dir) -> Optional[str]:
+    """The `org/repo` slug of `start_dir`'s `origin` remote, or None."""
+    proc = _git(start_dir, "remote", "get-url", "origin")
+    if proc is None or proc.returncode != 0:
+        return None
+    return _normalize_remote_url(proc.stdout.strip())
+
+
+def resolve_repo_for_dir(cfg: dict, start_dir) -> Optional[dict]:
+    """Resolve `start_dir` to a single configured repo.
+
+    Returns `{"key", "github", "matched_by"}` (matched_by is "local" or
+    "remote") when exactly one repo matches, else None. None covers: no repos
+    configured, dir isn't a git repo, no match, or an ambiguous (>1) match —
+    callers treat all of these as "don't auto-scope."
+    """
+    repos = cfg.get("repos") or {}
+    if not repos:
+        return None
+
+    # --- local clone path (primary) ---
+    top = _toplevel(start_dir)
+    if top is not None:
+        local_keys = []
+        for key, entry in repos.items():
+            local_raw = (entry or {}).get("local")
+            if not local_raw:
+                continue
+            try:
+                cfg_root = Path(local_raw).expanduser().resolve()
+            except OSError:
+                continue
+            if cfg_root == top:
+                local_keys.append(key)
+        if len(local_keys) == 1:
+            key = local_keys[0]
+            return {"key": key,
+                    "github": (repos[key] or {}).get("github"),
+                    "matched_by": "local"}
+        if len(local_keys) > 1:
+            # Ambiguous local config — refuse to guess.
+            return None
+
+    # --- git origin remote (fallback) ---
+    slug = _origin_slug(start_dir)
+    if slug:
+        remote_keys = [
+            key for key, entry in repos.items()
+            if entry and entry.get("github") and entry["github"].lower() == slug
+        ]
+        if len(remote_keys) == 1:
+            key = remote_keys[0]
+            return {"key": key,
+                    "github": repos[key].get("github"),
+                    "matched_by": "remote"}
+
+    return None

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

@@ -23,8 +23,13 @@ def detect_drift(body: str, github_issues: list[dict]) -> list[dict]:
                 continue
             gh_state = state_by_num[num]
             looks_closed = any(k in body_status for k in ("✅", "shipped", "merged", "closed"))
-            looks_open = "🔲" in body_status or "open" in body_status
 
+            # Asymmetric by design: CLOSED is terminal, so a closed issue whose
+            # row doesn't explicitly read closed (open marker, ambiguous, or empty)
+            # is drift. OPEN is not terminal — an open issue legitimately sits in
+            # many states (in-progress, blocked, todo), so only an explicit closed
+            # marker contradicts it. A broad open-side check (`not looks_open`)
+            # would false-positive every in-progress row, which is why we don't.
             if gh_state == "CLOSED" and not looks_closed:
                 drift.append({"issue": num, "body_status": body_status, "github_state": "CLOSED"})
             elif gh_state == "OPEN" and looks_closed:

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

@@ -1,6 +1,6 @@
 """Build the versioned viewer export structure from tracks + fetched issues."""
 from lib.github_state import format_assignees, short_milestone
-from lib.next_up import resolve_next_up_order
+from lib.next_up import resolve_next_up_order, suggest_next_up
 
 SCHEMA = 1
 
@@ -86,7 +86,7 @@ def normalize_issue(i: dict, in_progress: bool = False,
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None, config_repos=None,
                  plan_by_track=None, hot_by_track=None,
-                 next_up_default=None) -> dict:
+                 next_up_default=None, tier_duplicates=None) -> dict:
     plan_by_track = plan_by_track or {}
     hot_by_track = hot_by_track or {}
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
@@ -110,9 +110,22 @@ def build_export(tracks, issues_by_track, visibility, now: str,
         issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")
         closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
-        next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
         track_path = getattr(t, "path", None)
-        next_up_preset_name, _ = resolve_next_up_order(t.meta, next_up_default)
+        next_up_preset_name, next_up_order = resolve_next_up_order(t.meta, next_up_default)
+        # When `next_up_auto: true`, derive the next-up list live from the track's
+        # open issues using the resolved ranking preset — same as brief/orient —
+        # instead of reading the curated `next_up` frontmatter list. This is what
+        # surfaces the ranking in the viewer (which only reads this export). #326.
+        if t.meta.get("next_up_auto") and raw:
+            in_progress_set = {i["number"] for i in raw if issue_in_progress(i, hot)}
+            next_up = suggest_next_up(
+                raw, t.meta.get("blockers") or [],
+                track_milestone=milestone_alignment or None,
+                in_progress_nums=in_progress_set,
+                order=next_up_order,
+            )
+        else:
+            next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
@@ -140,6 +153,11 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "plan": plan_by_track.get(t.name),
             # Effective next_up ranking preset for this track (#326 Phase 2).
             "next_up_preset": next_up_preset_name,
+            # True when the track has `next_up_auto: true` set in its frontmatter,
+            # meaning the next-up list is auto-derived from the ranking preset (#326).
+            # Reflects the SETTING, not whether derivation actually ran (so the
+            # viewer toggle shows On even when a track has zero open issues).
+            "next_up_auto": bool(t.meta.get("next_up_auto")),
         })
     out["untracked"] = [
         {"repo": repo, "issues": [normalize_issue(r) for r in rows]}
@@ -151,4 +169,9 @@ def build_export(tracks, issues_by_track, visibility, now: str,
     # the starting point for adding fresh tracks. Each entry:
     # {folder, repo(slug), local, has_local, visibility}.
     out["repos"] = list(config_repos or [])
+    # Shared/private tier duplicates (#361, additive): tracks that exist in both
+    # a repo's shared .work-plan/ and the private notes_root tier. Read-only
+    # health signal for the viewer; resolved with the `dedupe-tiers` CLI verb.
+    # Each entry: {repo, folder, name, shared_path, private_path, safe}.
+    out["tier_duplicates"] = list(tier_duplicates or [])
     return out

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

@@ -0,0 +1,134 @@
+"""Deterministic, offline track suggestions for untracked issues (#373).
+
+The LLM path (`auto-triage` → a Claude session writes the answers) is the
+higher-quality source, but it only produces suggestions when an agent is driving.
+This module is the no-LLM fallback: it scores each untracked issue against each
+candidate track using only signals already in hand (no network, no model), so the
+VS Code Suggested bucket works standalone.
+
+It emits the SAME v2 answer entries the LLM path does
+(`{issue, verdict, track, runner_up, confidence, margin, rationale}`) so the
+viewer and `auto-triage --apply` consume it unchanged — abstain-first, with a
+grounded rationale naming the concrete signal that matched.
+
+Signals (all local, all explainable):
+  * milestone match  — issue.milestone == track.milestone_alignment (strong)
+  * track-label match — issue labels ∩ the track's reconcile labels
+                        (github.labels, else the default `track/<slug>`) (strong)
+  * keyword overlap  — issue-title tokens ∩ the track's slug/name/scope tokens
+                       (medium; capped)
+
+Confidence here is a heuristic score, NOT a calibrated probability — the answer
+doc is stamped `source: "heuristic"` so the viewer can flag it as lower-trust.
+"""
+import re
+
+# Weights are deliberately simple and sum-clamped to 1.0. Tuned so a single
+# strong signal alone stays below the default suggest bar (0.3 < 0.4/0.5), i.e.
+# one weak coincidence won't auto-suggest, but a strong signal does clear it.
+_W_MILESTONE = 0.5
+_W_LABEL = 0.4
+_W_KEYWORD_EACH = 0.1
+_W_KEYWORD_CAP = 0.3
+
+# Short / structural words that carry no track-matching signal.
+_STOPWORDS = frozenset((
+    "the", "a", "an", "and", "or", "to", "of", "for", "in", "on", "with", "is",
+    "add", "fix", "update", "support", "make", "use", "new", "issue", "bug",
+    "feat", "feature", "error", "when", "after", "before", "via", "from", "into",
+))
+
+
+def _tokens(text):
+    """Lowercase alphanumeric tokens of length ≥ 3, minus stopwords."""
+    if not text:
+        return set()
+    return {
+        t for t in re.split(r"[^a-z0-9]+", str(text).lower())
+        if len(t) >= 3 and t not in _STOPWORDS
+    }
+
+
+def _track_labels(track):
+    """A track's effective reconcile labels (lowercased): github.labels if set,
+    else the default `track/<slug>` — mirrors reconcile's resolution (#373)."""
+    labels = (track.get("labels") or [])
+    if labels:
+        return {str(x).lower() for x in labels}
+    slug = track.get("slug") or ""
+    return {f"track/{slug}".lower()} if slug else set()
+
+
+def score_suggestions(untracked, tracks, *, min_score=0.3, margin_gap=0.15):
+    """Score each untracked issue against the candidate tracks and return v2
+    suggestion entries (abstain-first).
+
+    `untracked`: [{"number", "title", "milestone": {"title"} | None,
+                   "labels": [{"name"}]}] (the auto-triage batch shape).
+    `tracks`:    [{"slug", "name", "milestone", "scope", "labels": [..]}].
+    `min_score`: a track must clear this for a non-abstain suggestion.
+    `margin_gap`: top must beat the runner-up by at least this for margin "clear".
+    """
+    out = []
+    for iss in untracked:
+        try:
+            num = int(iss.get("number"))
+        except (TypeError, ValueError):
+            continue
+
+        title_tokens = _tokens(iss.get("title"))
+        ms = iss.get("milestone") or {}
+        iss_ms = ms.get("title") if isinstance(ms, dict) else None
+        iss_labels = {str(lb.get("name", "")).lower()
+                      for lb in (iss.get("labels") or []) if isinstance(lb, dict)}
+
+        scored = []  # (score, slug, rationale-parts)
+        for t in tracks:
+            slug = t.get("slug")
+            if not slug:
+                continue
+            score = 0.0
+            reasons = []
+
+            t_ms = t.get("milestone")
+            if iss_ms and t_ms and iss_ms == t_ms:
+                score += _W_MILESTONE
+                reasons.append(f"milestone {iss_ms}")
+
+            shared_labels = iss_labels & _track_labels(t)
+            if shared_labels:
+                score += _W_LABEL
+                reasons.append("label " + ", ".join(sorted(shared_labels)))
+
+            t_kw = _tokens(slug) | _tokens(t.get("name")) | _tokens(t.get("scope"))
+            shared_kw = title_tokens & t_kw
+            if shared_kw:
+                score += min(_W_KEYWORD_CAP, _W_KEYWORD_EACH * len(shared_kw))
+                reasons.append("keyword " + ", ".join(sorted(shared_kw)))
+
+            if score > 0:
+                scored.append((round(min(score, 1.0), 2), slug, reasons))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+
+        if not scored or scored[0][0] < min_score:
+            out.append({
+                "issue": num,
+                "verdict": "abstain",
+                "rationale": "no track clears the heuristic bar",
+            })
+            continue
+
+        top = scored[0]
+        runner = scored[1] if len(scored) > 1 else None
+        clear = runner is None or (top[0] - runner[0]) >= margin_gap
+        out.append({
+            "issue": num,
+            "verdict": "suggest",
+            "track": top[1],
+            **({"runner_up": runner[1]} if runner else {}),
+            "confidence": top[0],
+            "margin": "clear" if clear else "narrow",
+            "rationale": "; ".join(top[2]),
+        })
+    return out

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

@@ -0,0 +1,152 @@
+"""Compare-and-swap guard for track-membership writes (#241).
+
+Slotting an issue into a track edits `meta["github"]["issues"]`. Shared-tier
+tracks travel via git push/pull, so an assisted or background write can race
+another session or a teammate's pull. `lib.frontmatter.write_file` is a blind
+overwrite, so without a guard the last writer silently wins.
+
+This module adds two things:
+
+  * `issues_fingerprint(meta)` — a deterministic digest of the membership list
+    ONLY. We fingerprint just `github.issues`, not the whole frontmatter or the
+    body: those carry fields other commands legitimately rewrite concurrently
+    (`refresh-md` stamps `last_touched`, `handoff` rewrites the body table), and
+    fingerprinting them would abort on changes that have nothing to do with the
+    list we're about to overwrite. The membership list is exactly the CAS surface.
+
+  * `guarded_membership_write(...)` — ALWAYS re-reads the file from disk
+    immediately before writing, applies the membership delta to the FRESH
+    frontmatter, and writes back the rest of the frontmatter and the body
+    unchanged. So a concurrent edit to the body OR to other frontmatter fields
+    (status, last_touched, depends_on, …) is preserved — only the issues list is
+    replaced. When `expect` is supplied and the on-disk membership no longer
+    matches it, the write is ABORTED and a `{"stale": ...}` signal is returned
+    instead of overwriting — the caller re-prompts on fresh state. When `expect`
+    is None (the manual single-writer path) the abort is skipped, but the
+    re-read + merge still happens: strictly safer than a blind overwrite, with
+    the same observable result for a lone writer.
+
+Scope of the guarantee (deliberately narrow — don't oversell it):
+  - This is a check-then-act, not a locked atomic CAS: `parse_file` then
+    `write_file` are separate syscalls with no file lock, so a writer landing in
+    the sub-millisecond window between them isn't caught. `expect` narrows the
+    window vs. a blind overwrite; it does not eliminate it. Adequate for the real
+    usage (interactive single user + occasional same-machine background).
+  - `shared_rebase_guard` lands a shared-tier write on top of origin AS OF THE
+    LAST FETCH; it is NOT a cross-machine atomic CAS against origin. A teammate
+    pushing between the rebase and the eventual (separate) push is reconciled by
+    the non-fast-forward push being rejected + rebase-on-next-write, not by this
+    write path.
+  - `frontmatter.write_file` re-serializes the frontmatter via yq on every
+    write, so body-only edits round-trip verbatim but YAML comments / key order
+    are normalized (a pre-existing property, not introduced here).
+"""
+import hashlib
+import json
+from pathlib import Path
+
+from lib.frontmatter import parse_file, write_file
+
+
+def _issue_set(meta: dict) -> set:
+    """The frontmatter's github.issues as a set of ints (malformed entries
+    dropped — the file may be hand-edited)."""
+    out = set()
+    for n in (meta.get("github", {}).get("issues") or []):
+        try:
+            out.add(int(n))
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def issues_fingerprint(meta: dict) -> str:
+    """Deterministic sha256[:16] of the sorted github.issues list.
+
+    Order-independent (sorted) and stable across runs (no randomness — 3.9
+    stdlib). Two metas with the same membership produce the same fingerprint
+    regardless of list order or unrelated frontmatter differences.
+    """
+    payload = json.dumps(sorted(_issue_set(meta)), separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def guarded_membership_write(path, *, add_nums=(), remove_nums=(), expect=None):
+    """Re-read `path`, apply the membership delta to the fresh frontmatter, and
+    write back the fresh body unchanged.
+
+    Returns one of:
+      {"stale": True, "reason": str, "current": [int]}
+          — `expect` was supplied and the on-disk membership no longer matches
+            it; NO write happened. `current` is the fresh on-disk list so the
+            caller can re-offer against it.
+      {"written": [int]}
+          — wrote successfully; the value is the final sorted membership list.
+
+    `expect` is the `issues_fingerprint` the caller captured when it built the
+    operation (e.g. when the viewer rendered the offer). Pass None for the
+    unguarded manual path.
+    """
+    fresh_meta, fresh_body = parse_file(Path(path))
+
+    if expect is not None and issues_fingerprint(fresh_meta) != expect:
+        return {
+            "stale": True,
+            "reason": "track membership changed since the operation was prepared",
+            "current": sorted(_issue_set(fresh_meta)),
+        }
+
+    issues = _issue_set(fresh_meta)
+    issues |= {int(n) for n in add_nums}
+    issues -= {int(n) for n in remove_nums}
+    final = sorted(issues)
+    fresh_meta.setdefault("github", {})["issues"] = final
+    write_file(Path(path), fresh_meta, fresh_body)
+    return {"written": final}
+
+
+def shared_rebase_guard(target, cfg):
+    """Before writing a SHARED-tier track pinned to a `plan_branch`, fetch +
+    rebase its worktree onto origin so the write lands on top of a teammate's
+    pushed plan changes (#241). Best-effort: this reduces the cross-machine
+    (git push/pull) race, it does not make the write atomic against origin — a
+    teammate pushing after the rebase is reconciled by the non-fast-forward push
+    rejection + rebase-on-next-write, not here. The fingerprint CAS covers the
+    same-machine race.
+
+    Returns (ok: bool, reason: str | None):
+      (True, None)        — safe to proceed: the track is private, a legacy
+                            shared track (no plan_branch → working-tree tier), or
+                            the worktree rebased cleanly / had no upstream.
+      (False, reason)     — the shared branch diverged and could NOT auto-rebase;
+                            the caller MUST abort and surface {needs_rebase}
+                            rather than blind-write over a diverged branch.
+
+    Never raises — an unexpected guard error degrades to "proceed" (consistent
+    with the toolkit's never-break-the-command VCS philosophy; the underlying
+    plan_worktree ops are themselves never-raise).
+    """
+    try:
+        if getattr(target, "tier", None) != "shared":
+            return (True, None)
+        repos = (cfg or {}).get("repos", {}) or {}
+        entry = repos.get(getattr(target, "folder", None))
+        if entry is None:
+            for e in repos.values():
+                if e and e.get("github") == getattr(target, "repo", None):
+                    entry = e
+                    break
+        branch = entry.get("plan_branch") if entry else None
+        local = entry.get("local") if entry else None
+        if not branch or not local:
+            return (True, None)  # legacy shared tier (working tree) — no rebase
+        from lib import plan_worktree
+        worktree = plan_worktree.ensure_worktree(Path(local).expanduser(), branch)
+        if worktree is None:
+            return (True, None)  # can't ensure the worktree — degrade, proceed
+        if not plan_worktree.rebase_onto_origin(worktree, branch):
+            return (False, f"shared plan branch '{branch}' diverged and could not "
+                           f"auto-rebase; resolve manually")
+        return (True, None)
+    except Exception:
+        return (True, None)