@stylusnexus/work-plan 2026.6.16 → 2026.6.18

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)

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

@@ -267,6 +267,43 @@ def is_published(local_path: Path, branch: str) -> bool:
     return remote_branch_exists(local_path, branch)
 
 
+def rebase_onto_origin(worktree: Path, branch: str) -> bool:
+    """Fetch origin/<branch> and rebase the worktree (checked out at <branch>)
+    onto it, so a shared-tier write lands on top of any teammate's pushed plan
+    changes instead of diverging (#241).
+
+    Returns:
+      True  — the worktree is now at-or-ahead of origin: rebase succeeded,
+              there was nothing to replay, or the branch isn't published yet
+              (local is authoritative — nothing to rebase onto).
+      False — the rebase hit a conflict (it is ABORTED so the worktree is left
+              clean, never half-rebased) or git couldn't run. The caller must
+              NOT write — it surfaces {needs_rebase} and bails.
+
+    Never raises.
+    """
+    wt = Path(worktree).expanduser()
+    # Fetch so origin/<branch> is authoritative before we compare.
+    fetch_branch(wt, branch)
+    if not remote_branch_exists(wt, branch):
+        return True  # unpublished — no upstream to rebase onto; local wins
+    # --autostash: the normal flow is write-file-then-commit, so the worktree's
+    # .work-plan/ is routinely dirty when we rebase. Without autostash git would
+    # refuse the rebase on the dirty precondition and we'd report a spurious
+    # {needs_rebase}; autostash shelves the local edits, rebases, and reapplies
+    # them on top — so a clean rebase succeeds even with pending plan edits.
+    proc = _git(wt, "rebase", "--autostash", f"origin/{branch}")
+    if proc is None:
+        return False
+    if proc.returncode == 0:
+        return True
+    # True conflict (autostash reapply or replayed commits): abort so the
+    # worktree is never left in a partially-rebased state. A blind write over a
+    # diverged shared branch is exactly what this guard exists to prevent.
+    _git(wt, "rebase", "--abort")
+    return False
+
+
 def unpushed_oneline(local_path: Path, branch: str) -> list:
     """One-line summaries of commits on local `branch` not yet on origin
     (`origin/<branch>..<branch>`). If origin/<branch> doesn't exist, every commit

package/skills/work-plan/tests/test_auto_triage.py

@@ -347,5 +347,108 @@ class AutoTriageApplyTest(unittest.TestCase):
         self.assertIn("0 issue(s) assigned", buf.getvalue())
 
 
+class AutoTriageJsonScanTest(unittest.TestCase):
+    """--json scan mode (#241): emit a machine batch with a batch_id."""
+
+    def test_json_mode_emits_batch_with_id_and_prompt(self):
+        cfg = _make_cfg()
+        tracks = [_make_track("auth-flow", "org/myrepo", [])]
+        rc, out, _ = _drive_prepare(["--json"], cfg=cfg, tracks=tracks,
+                                    open_issues=_open_issues(4501, 4502))
+        self.assertEqual(rc, 0)
+        data = json.loads(out.strip())  # stdout is a single JSON object
+        self.assertIn("batch_id", data)
+        self.assertTrue(data["batch_id"])
+        self.assertEqual({i["number"] for i in data["untracked"]}, {4501, 4502})
+        self.assertIn("prompt", data)
+        self.assertIn("answers_path", data)
+        # Track entries carry scope text for grounded matching.
+        self.assertIn("scope", data["tracks"][0])
+
+
+class AutoTriageHeuristicTest(unittest.TestCase):
+    """--heuristic (#373): the CLI writes the v2 answers file itself, no LLM."""
+
+    def test_heuristic_writes_answers_file_with_source_and_batch_id(self):
+        cfg = _make_cfg()
+        track = _make_track("auth-flow", "org/myrepo", [], slug="auth-flow")
+        track.meta["milestone_alignment"] = "v0.4"
+        open_issues = [{"number": 4501, "title": "auth thing", "state": "OPEN",
+                        "milestone": {"title": "v0.4"}, "labels": []}]
+        with tempfile.TemporaryDirectory() as tmp:
+            batch_file = Path(tmp) / "auto_triage.org_myrepo.json"
+            answers_file = Path(tmp) / "auto_triage.org_myrepo.answers.json"
+            with patch("commands.auto_triage.load_config", return_value=cfg), \
+                 patch("commands.auto_triage.discover_tracks", return_value=[track]), \
+                 patch("commands.auto_triage.fetch_open_issues", return_value=open_issues), \
+                 patch("commands.auto_triage._batch_path", return_value=batch_file), \
+                 patch("commands.auto_triage._answers_path", return_value=answers_file):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = auto_triage.run(["--heuristic"])
+            self.assertEqual(rc, 0)
+            self.assertTrue(answers_file.exists(), "heuristic must write the answers file")
+            doc = json.loads(answers_file.read_text())
+            self.assertEqual(doc["version"], 2)
+            self.assertEqual(doc["source"], "heuristic")
+            batch = json.loads(batch_file.read_text())
+            self.assertEqual(doc["batch_id"], batch["batch_id"])  # correlates
+            sug = doc["suggestions"][0]
+            self.assertEqual(sug["issue"], 4501)
+            self.assertEqual(sug["verdict"], "suggest")
+            self.assertEqual(sug["track"], "auth-flow")
+
+
+class AutoTriageV2AnswersTest(unittest.TestCase):
+    """v2 abstain-first answers schema (#241) + back-compat with v1."""
+
+    def _batch(self, nums, batch_id="abc123"):
+        return {"batch_id": batch_id, "repo": "org/myrepo", "folder": "myrepo",
+                "untracked": [{"number": n} for n in nums]}
+
+    def test_v2_applies_only_clear_suggestions(self):
+        cfg = _make_cfg()
+        track = _make_track("auth-flow", "org/myrepo", [], slug="auth-flow")
+        answers = {"version": 2, "batch_id": "abc123", "suggestions": [
+            {"issue": 4501, "verdict": "suggest", "track": "auth-flow",
+             "margin": "clear", "confidence": 0.9, "rationale": "label area/auth"},
+            {"issue": 4502, "verdict": "suggest", "track": "auth-flow",
+             "margin": "narrow", "confidence": 0.55, "rationale": "maybe"},
+            {"issue": 4507, "verdict": "abstain", "rationale": "no fit"},
+        ]}
+        rc, mwrite, out = _drive_apply(cfg=cfg, tracks=[track],
+                                       batch=self._batch([4501, 4502, 4507]),
+                                       answers=answers)
+        self.assertEqual(rc, 0)
+        mwrite.assert_called_once()  # only the clear suggestion is written
+        written = mwrite.call_args[0][1]["github"]["issues"]
+        self.assertIn(4501, written)
+        self.assertNotIn(4502, written)  # narrow margin → left untracked
+        self.assertNotIn(4507, written)  # abstained → left untracked
+
+    def test_v1_answers_still_apply(self):
+        cfg = _make_cfg()
+        track = _make_track("auth-flow", "org/myrepo", [], slug="auth-flow")
+        answers = [{"track": "auth-flow", "issues": [4501]}]  # legacy shape
+        rc, mwrite, out = _drive_apply(cfg=cfg, tracks=[track],
+                                       batch=self._batch([4501]), answers=answers)
+        self.assertEqual(rc, 0)
+        mwrite.assert_called_once()
+        self.assertIn(4501, mwrite.call_args[0][1]["github"]["issues"])
+
+    def test_batch_id_mismatch_warns_but_applies(self):
+        cfg = _make_cfg()
+        track = _make_track("auth-flow", "org/myrepo", [], slug="auth-flow")
+        answers = {"version": 2, "batch_id": "STALE", "suggestions": [
+            {"issue": 4501, "verdict": "suggest", "track": "auth-flow",
+             "margin": "clear", "rationale": "label area/auth"}]}
+        rc, mwrite, out = _drive_apply(cfg=cfg, tracks=[track],
+                                       batch=self._batch([4501], batch_id="abc123"),
+                                       answers=answers)
+        self.assertEqual(rc, 0)
+        self.assertIn("older scan", out)
+        mwrite.assert_called_once()
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/tests/test_batch_slot.py

@@ -52,11 +52,21 @@ def _drive(args, tracks=None, vis="PRIVATE"):
     cfg = {"notes_root": "/tmp/fake-notes", "repos": {"ok": {"github": "ok/repo"}}}
     gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
 
+    # Writes go through lib.membership_guard (re-read via parse_file, write via
+    # write_file). Returning each track's own meta/body lets the guard mutate
+    # them in place, so assertions on track.meta still observe the merge.
+    by_path = {str(t.path): t for t in tracks}
+
+    def fake_parse(p):
+        t = by_path[str(p)]
+        return (t.meta, t.body)
+
     with patch("commands.batch_slot.load_config", return_value=cfg), \
          patch("commands.batch_slot.discover_tracks", return_value=tracks), \
          patch("commands.batch_slot.subprocess.run", return_value=gh_proc), \
          patch("lib.write_guard.repo_visibility", return_value=vis), \
-         patch("commands.batch_slot.write_file") as mw:
+         patch("lib.membership_guard.parse_file", side_effect=fake_parse), \
+         patch("lib.membership_guard.write_file") as mw:
         buf = io.StringIO()
         with redirect_stdout(buf):
             rc = batch_slot.run(args)
@@ -272,6 +282,12 @@ class BatchSlotTest(unittest.TestCase):
         def _raise(*a, **kw):
             raise AssertionError("input() must not be called on non-interactive path")
 
+        by_path = {str(t.path): t for t in (source, target)}
+
+        def fake_parse(p):
+            t = by_path[str(p)]
+            return (t.meta, t.body)
+
         with patch("builtins.input", side_effect=_raise), \
              patch("lib.prompts.prompt_input", side_effect=_raise):
             cfg = {"notes_root": "/tmp/fake-notes", "repos": {"ok": {"github": "ok/repo"}}}
@@ -280,7 +296,8 @@ class BatchSlotTest(unittest.TestCase):
                  patch("commands.batch_slot.discover_tracks", return_value=[source, target]), \
                  patch("commands.batch_slot.subprocess.run", return_value=gh_proc), \
                  patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
-                 patch("commands.batch_slot.write_file"):
+                 patch("lib.membership_guard.parse_file", side_effect=fake_parse), \
+                 patch("lib.membership_guard.write_file"):
                 buf = io.StringIO()
                 with redirect_stdout(buf):
                     rc = batch_slot.run(["42", "beta", "--move"])

package/skills/work-plan/tests/test_heuristic_triage.py

@@ -0,0 +1,114 @@
+"""Tests for lib.heuristic_triage — the offline (no-LLM) track scorer (#373).
+
+Covers: milestone match, track-label overlap (incl. the track/<slug> default),
+keyword overlap, abstain when nothing clears the bar, margin clear-vs-narrow from
+the top-vs-runner gap, and the v2 entry shape.
+"""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.heuristic_triage import score_suggestions
+
+
+def _iss(number, title="", milestone=None, labels=()):
+    return {
+        "number": number,
+        "title": title,
+        "milestone": {"title": milestone} if milestone else None,
+        "labels": [{"name": n} for n in labels],
+    }
+
+
+def _trk(slug, name=None, milestone=None, scope="", labels=None):
+    return {"slug": slug, "name": name or slug, "milestone": milestone,
+            "scope": scope, "labels": labels}
+
+
+class HeuristicScoreTest(unittest.TestCase):
+
+    def _one(self, entries):
+        self.assertEqual(len(entries), 1)
+        return entries[0]
+
+    def test_milestone_match_suggests(self):
+        e = self._one(score_suggestions(
+            [_iss(1, "rate limit", milestone="v0.4")],
+            [_trk("auth-flow", milestone="v0.4")],
+        ))
+        self.assertEqual(e["verdict"], "suggest")
+        self.assertEqual(e["track"], "auth-flow")
+        self.assertIn("milestone v0.4", e["rationale"])
+
+    def test_track_label_overlap_suggests(self):
+        e = self._one(score_suggestions(
+            [_iss(2, "something", labels=["area/auth"])],
+            [_trk("auth-flow", labels=["area/auth"])],
+        ))
+        self.assertEqual(e["verdict"], "suggest")
+        self.assertIn("label area/auth", e["rationale"])
+
+    def test_default_track_slug_label(self):
+        # No github.labels on the track → default `track/<slug>` is matched.
+        e = self._one(score_suggestions(
+            [_iss(3, "x", labels=["track/auth-flow"])],
+            [_trk("auth-flow", labels=None)],
+        ))
+        self.assertEqual(e["verdict"], "suggest")
+
+    def test_keyword_only_below_bar_abstains(self):
+        # A single keyword hit (0.1) is below the 0.3 suggest bar → abstain.
+        e = self._one(score_suggestions(
+            [_iss(4, "sessions cleanup")],
+            [_trk("tabletop-sessions", name="tabletop sessions")],
+        ))
+        self.assertEqual(e["verdict"], "abstain")
+
+    def test_no_signal_abstains(self):
+        e = self._one(score_suggestions(
+            [_iss(5, "totally unrelated billing thing")],
+            [_trk("auth-flow", milestone="v0.4")],
+        ))
+        self.assertEqual(e["verdict"], "abstain")
+        self.assertNotIn("track", e)
+
+    def test_margin_narrow_when_two_tracks_tie(self):
+        # Both tracks share the milestone → equal top score → narrow margin.
+        e = self._one(score_suggestions(
+            [_iss(6, "x", milestone="v0.4")],
+            [_trk("auth-flow", milestone="v0.4"), _trk("idea-mode", milestone="v0.4")],
+        ))
+        self.assertEqual(e["verdict"], "suggest")
+        self.assertEqual(e["margin"], "narrow")
+        self.assertIn("runner_up", e)
+
+    def test_margin_clear_when_one_track_dominates(self):
+        e = self._one(score_suggestions(
+            [_iss(7, "auth rate limit", milestone="v0.4", labels=["area/auth"])],
+            [_trk("auth-flow", name="auth flow", milestone="v0.4", labels=["area/auth"]),
+             _trk("idea-mode", milestone="v9.9")],
+        ))
+        self.assertEqual(e["margin"], "clear")
+        self.assertEqual(e["track"], "auth-flow")
+
+    def test_confidence_clamped_and_in_range(self):
+        e = self._one(score_suggestions(
+            [_iss(8, "auth flow rate limit session token scope",
+                  milestone="v0.4", labels=["area/auth"])],
+            [_trk("auth-flow", name="auth flow", milestone="v0.4",
+                  scope="auth rate limit session token scope", labels=["area/auth"])],
+        ))
+        self.assertLessEqual(e["confidence"], 1.0)
+        self.assertGreaterEqual(e["confidence"], 0.3)
+
+    def test_malformed_issue_number_skipped(self):
+        entries = score_suggestions([{"number": "not-an-int", "title": "x"}],
+                                    [_trk("a")])
+        self.assertEqual(entries, [])
+
+
+if __name__ == "__main__":
+    unittest.main()