@stylusnexus/work-plan 2026.6.15 → 2026.6.18

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

@@ -0,0 +1,116 @@
+"""Tests for lib.membership_guard — the compare-and-swap guard (#241).
+
+Covers:
+- issues_fingerprint is order-independent and stable, and ignores non-issue
+  frontmatter (last_touched / body differences don't change it).
+- guarded_membership_write merges add/remove onto the FRESH on-disk frontmatter.
+- A concurrent body-only edit is preserved (the fresh body is written back).
+- expect-match writes; expect-mismatch returns {stale} and does NOT write.
+- expect=None never aborts (the manual single-writer path).
+
+All file I/O is exercised against a real temp file (no yq mock needed — these go
+through lib.frontmatter end to end), so the round-trip is real.
+"""
+import sys
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.frontmatter import parse_file, write_file
+from lib.membership_guard import issues_fingerprint, guarded_membership_write
+
+
+def _meta(issues, repo="ok/repo", **extra):
+    m = {"track": "alpha", "status": "active", "github": {"repo": repo, "issues": list(issues)}}
+    m.update(extra)
+    return m
+
+
+class FingerprintTest(unittest.TestCase):
+
+    def test_order_independent(self):
+        self.assertEqual(
+            issues_fingerprint(_meta([3, 1, 2])),
+            issues_fingerprint(_meta([1, 2, 3])),
+        )
+
+    def test_changes_when_membership_changes(self):
+        self.assertNotEqual(
+            issues_fingerprint(_meta([1, 2])),
+            issues_fingerprint(_meta([1, 2, 3])),
+        )
+
+    def test_ignores_non_issue_frontmatter(self):
+        """last_touched / other fields must not affect the fingerprint, else the
+        guard would abort on unrelated concurrent edits."""
+        self.assertEqual(
+            issues_fingerprint(_meta([1, 2], last_touched="2026-01-01")),
+            issues_fingerprint(_meta([1, 2], last_touched="2026-06-17")),
+        )
+
+    def test_empty_and_missing_github_are_stable(self):
+        self.assertEqual(issues_fingerprint({}), issues_fingerprint(_meta([])))
+
+
+class GuardedWriteTest(unittest.TestCase):
+
+    def setUp(self):
+        self._tmp = TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "alpha.md"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _seed(self, issues, body="# body\n"):
+        write_file(self.path, _meta(issues), body)
+
+    def test_add_merges_onto_disk(self):
+        self._seed([10, 20])
+        res = guarded_membership_write(self.path, add_nums=[30])
+        self.assertEqual(res, {"written": [10, 20, 30]})
+        meta, _ = parse_file(self.path)
+        self.assertEqual(meta["github"]["issues"], [10, 20, 30])
+
+    def test_remove_merges_onto_disk(self):
+        self._seed([10, 20, 30])
+        res = guarded_membership_write(self.path, remove_nums=[20])
+        self.assertEqual(res, {"written": [10, 30]})
+
+    def test_preserves_concurrent_body_edit(self):
+        """Re-reads body at write time, so a body change made after the caller's
+        snapshot is preserved rather than clobbered."""
+        self._seed([10], body="# original\n")
+        # Simulate another process rewriting ONLY the body (e.g. handoff).
+        meta, _ = parse_file(self.path)
+        write_file(self.path, meta, "# rewritten by another writer\n")
+        guarded_membership_write(self.path, add_nums=[20])
+        _, body = parse_file(self.path)
+        self.assertIn("rewritten by another writer", body)
+
+    def test_expect_match_writes(self):
+        self._seed([10, 20])
+        fp = issues_fingerprint(_meta([10, 20]))
+        res = guarded_membership_write(self.path, add_nums=[30], expect=fp)
+        self.assertEqual(res, {"written": [10, 20, 30]})
+
+    def test_expect_mismatch_aborts_without_writing(self):
+        self._seed([10, 20])
+        stale_fp = issues_fingerprint(_meta([10]))  # what the caller THOUGHT it saw
+        res = guarded_membership_write(self.path, add_nums=[30], expect=stale_fp)
+        self.assertTrue(res["stale"])
+        self.assertEqual(res["current"], [10, 20])
+        # Nothing was written — disk is unchanged.
+        meta, _ = parse_file(self.path)
+        self.assertEqual(meta["github"]["issues"], [10, 20])
+
+    def test_expect_none_never_aborts(self):
+        self._seed([10, 20])
+        res = guarded_membership_write(self.path, add_nums=[30], expect=None)
+        self.assertIn("written", res)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,22 @@
+"""which-repo is dispatchable + documented (#358/#357 Phase 1)."""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+import work_plan
+
+
+class RegisterWhichRepoTest(unittest.TestCase):
+    def test_in_subcommands(self):
+        self.assertEqual(work_plan.SUBCOMMANDS["which-repo"], "commands.which_repo")
+
+    def test_in_descriptions(self):
+        names = {row[0] for row in work_plan.DESCRIPTIONS}
+        self.assertIn("which-repo", names)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -197,5 +197,100 @@ class SetNextUpTest(unittest.TestCase):
         self.assertIn("--order is ignored", err.getvalue())
 
 
+class SetNextUpAutoFlagTest(unittest.TestCase):
+    """Tests for --auto=on|off flag on set-next-up."""
+
+    def _drive_with_stderr(self, args, vis="PRIVATE", cfg=None, track=None):
+        """Like _drive but also captures stderr."""
+        base_cfg = {"notes_root": "/tmp"}
+        if cfg is not None:
+            base_cfg.update(cfg)
+        t = track if track is not None else _t()
+        with patch("commands.set_next_up.load_config", return_value=base_cfg), \
+             patch("commands.set_next_up.discover_tracks", return_value=[t]), \
+             patch("lib.write_guard.repo_visibility", return_value=vis), \
+             patch("commands.set_next_up.write_file") as mw:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = set_next_up.run(args)
+        return rc, mw, out.getvalue(), err.getvalue()
+
+    def test_auto_on_writes_next_up_auto_true(self):
+        """--auto=on sets next_up_auto: True in track meta."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+
+    def test_auto_off_removes_next_up_auto(self):
+        """--auto=off removes next_up_auto from track meta."""
+        t = _t(meta={"status": "active", "next_up_auto": True})
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_auto", meta)
+
+    def test_auto_off_on_track_without_key_still_succeeds(self):
+        """--auto=off on a track with no next_up_auto key still writes ok (no KeyError)."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertNotIn("next_up_auto", meta)
+
+    def test_auto_bogus_returns_rc2_no_write(self):
+        """--auto=bogus → rc=2 and no write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=bogus"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_auto_standalone_private_writes(self):
+        """--auto=on alone (no --preset/--order/--clear) is accepted on private repo."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+
+    def test_auto_standalone_public_needs_confirm(self):
+        """--auto=on alone on a PUBLIC repo → needs_confirm, no write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_auto_standalone_public_with_valid_confirm_writes(self):
+        """--auto=on alone on PUBLIC repo with valid --confirm token proceeds to write."""
+        tok = make_token("o/r", "ph")
+        rc, mw, out, err = self._drive_with_stderr(
+            ["ph", "--auto=on", f"--confirm={tok}"], vis="PUBLIC"
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+
+    def test_auto_on_combined_with_preset_writes_both(self):
+        """--auto=on --preset=backlog sets BOTH next_up_auto AND next_up_order in one write."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on", "--preset=backlog"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        meta = mw.call_args[0][1]
+        self.assertTrue(meta.get("next_up_auto"))
+        self.assertEqual(meta.get("next_up_order"), {"preset": "backlog"})
+
+    def test_auto_on_prints_success_message(self):
+        """--auto=on prints a clear success line."""
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=on"])
+        self.assertIn("next_up_auto", out)
+        self.assertIn("true", out.lower())
+
+    def test_auto_off_prints_success_message(self):
+        """--auto=off prints a clear success line."""
+        t = _t(meta={"status": "active", "next_up_auto": True})
+        rc, mw, out, err = self._drive_with_stderr(["ph", "--auto=off"], track=t)
+        self.assertIn("next_up_auto", out)
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -0,0 +1,154 @@
+"""Tests for the shared-tier rebase guard (#241 phase 2).
+
+Covers:
+- plan_worktree.rebase_onto_origin: clean rebase / nothing-to-do → True;
+  unpublished branch (no upstream) → True; conflict → abort + False;
+  git unavailable → False.
+- membership_guard.shared_rebase_guard: private track → no-op; legacy shared
+  (no plan_branch) → no-op; shared + plan_branch clean rebase → ok; divergence →
+  (False, reason).
+- slot integration: a shared track whose rebase diverges emits {needs_rebase}
+  and does NOT write.
+"""
+import io
+import json
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib import plan_worktree
+from lib.membership_guard import shared_rebase_guard
+
+
+def _git_stub(*, rebase_rc=0, remote_exists=True, rebase_none=False):
+    """Build a fake plan_worktree._git dispatching on the git subcommand."""
+    calls = []
+
+    def _git(cwd, *args, **kw):
+        calls.append(tuple(args))
+        head = args[0]
+        if head == "fetch":
+            return MagicMock(returncode=0, stdout="", stderr="")
+        if head == "rev-parse":
+            # remote_branch_exists → refs/remotes/origin/<branch>
+            rc = 0 if remote_exists else 1
+            return MagicMock(returncode=rc, stdout="", stderr="")
+        if head == "rebase" and args[-1] != "--abort":
+            if rebase_none:
+                return None
+            return MagicMock(returncode=rebase_rc, stdout="", stderr="conflict")
+        if args == ("rebase", "--abort"):
+            return MagicMock(returncode=0, stdout="", stderr="")
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    return _git, calls
+
+
+class RebaseOntoOriginTest(unittest.TestCase):
+
+    def test_clean_rebase_returns_true_with_autostash(self):
+        gitfn, calls = _git_stub(rebase_rc=0, remote_exists=True)
+        with patch("lib.plan_worktree._git", side_effect=gitfn):
+            self.assertTrue(plan_worktree.rebase_onto_origin(Path("/wt"), "work-plan/plan"))
+        # --autostash so a dirty .work-plan/ (the normal write-then-commit flow)
+        # doesn't make the rebase refuse with a spurious needs_rebase.
+        self.assertIn(("rebase", "--autostash", "origin/work-plan/plan"), calls)
+        self.assertNotIn(("rebase", "--abort"), calls)
+
+    def test_unpublished_branch_returns_true_without_rebasing(self):
+        gitfn, calls = _git_stub(remote_exists=False)
+        with patch("lib.plan_worktree._git", side_effect=gitfn):
+            self.assertTrue(plan_worktree.rebase_onto_origin(Path("/wt"), "work-plan/plan"))
+        self.assertNotIn(("rebase", "--autostash", "origin/work-plan/plan"), calls)
+
+    def test_conflict_aborts_and_returns_false(self):
+        gitfn, calls = _git_stub(rebase_rc=1, remote_exists=True)
+        with patch("lib.plan_worktree._git", side_effect=gitfn):
+            self.assertFalse(plan_worktree.rebase_onto_origin(Path("/wt"), "work-plan/plan"))
+        # Conflict must leave the worktree clean.
+        self.assertIn(("rebase", "--abort"), calls)
+
+    def test_git_unavailable_returns_false(self):
+        gitfn, calls = _git_stub(rebase_none=True, remote_exists=True)
+        with patch("lib.plan_worktree._git", side_effect=gitfn):
+            self.assertFalse(plan_worktree.rebase_onto_origin(Path("/wt"), "work-plan/plan"))
+
+
+class SharedRebaseGuardTest(unittest.TestCase):
+
+    CFG = {"repos": {"ok": {"github": "ok/repo", "local": "/repo",
+                            "plan_branch": "work-plan/plan"}}}
+
+    def _track(self, *, tier="shared", folder="ok", repo="ok/repo"):
+        return SimpleNamespace(name="alpha", tier=tier, folder=folder, repo=repo,
+                               path=Path("/wt/.work-plan/alpha.md"))
+
+    def test_private_track_is_noop(self):
+        ok, reason = shared_rebase_guard(self._track(tier="private"), self.CFG)
+        self.assertTrue(ok)
+        self.assertIsNone(reason)
+
+    def test_legacy_shared_no_plan_branch_is_noop(self):
+        cfg = {"repos": {"ok": {"github": "ok/repo", "local": "/repo"}}}  # no plan_branch
+        ok, reason = shared_rebase_guard(self._track(), cfg)
+        self.assertTrue(ok)
+
+    def test_shared_clean_rebase_ok(self):
+        with patch("lib.plan_worktree.ensure_worktree", return_value=Path("/wt")), \
+             patch("lib.plan_worktree.rebase_onto_origin", return_value=True):
+            ok, reason = shared_rebase_guard(self._track(), self.CFG)
+        self.assertTrue(ok)
+
+    def test_shared_divergence_blocks(self):
+        with patch("lib.plan_worktree.ensure_worktree", return_value=Path("/wt")), \
+             patch("lib.plan_worktree.rebase_onto_origin", return_value=False):
+            ok, reason = shared_rebase_guard(self._track(), self.CFG)
+        self.assertFalse(ok)
+        self.assertIn("diverged", reason)
+
+    def test_worktree_unavailable_degrades_to_proceed(self):
+        with patch("lib.plan_worktree.ensure_worktree", return_value=None):
+            ok, reason = shared_rebase_guard(self._track(), self.CFG)
+        self.assertTrue(ok)
+
+
+class SlotNeedsRebaseTest(unittest.TestCase):
+
+    def test_slot_aborts_with_needs_rebase_json_no_write(self):
+        from commands import slot
+        track = SimpleNamespace(
+            name="alpha", tier="shared", folder="ok", repo="ok/repo",
+            path=Path("/wt/.work-plan/alpha.md"), body="# x",
+            meta={"track": "alpha", "status": "active",
+                  "github": {"repo": "ok/repo", "issues": []}},
+            has_frontmatter=True,
+        )
+        cfg = {"notes_root": "/tmp/n",
+               "repos": {"ok": {"github": "ok/repo", "local": "/repo",
+                                "plan_branch": "work-plan/plan"}}}
+        gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
+        with patch("commands.slot.load_config", return_value=cfg), \
+             patch("commands.slot.discover_tracks", return_value=[track]), \
+             patch("commands.slot.subprocess.run", return_value=gh_proc), \
+             patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+             patch("lib.plan_worktree.ensure_worktree", return_value=Path("/wt")), \
+             patch("lib.plan_worktree.rebase_onto_origin", return_value=False), \
+             patch("lib.membership_guard.write_file") as mw:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = slot.run(["30", "alpha"])
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()  # divergence → no write
+        data = json.loads(buf.getvalue().strip())
+        self.assertTrue(data["needs_rebase"])
+        self.assertEqual(data["track"], "alpha")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -56,11 +56,22 @@ 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="")
 
+    # The write path now goes through lib.membership_guard, which re-reads the
+    # file (parse_file) and writes the merged result (write_file). Returning the
+    # track's own meta/body objects from parse_file 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.slot.load_config", return_value=cfg), \
          patch("commands.slot.discover_tracks", return_value=tracks), \
          patch("commands.slot.subprocess.run", return_value=gh_proc), \
          patch("lib.write_guard.repo_visibility", return_value=vis), \
-         patch("commands.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 = slot.run(args)
@@ -223,6 +234,12 @@ class SlotNonInteractiveTest(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"}}}
@@ -231,7 +248,8 @@ class SlotNonInteractiveTest(unittest.TestCase):
                  patch("commands.slot.discover_tracks", return_value=[source, target]), \
                  patch("commands.slot.subprocess.run", return_value=gh_proc), \
                  patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
-                 patch("commands.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):
                     # --move (prior owner path) + private repo (no confirm gate)
@@ -239,5 +257,79 @@ class SlotNonInteractiveTest(unittest.TestCase):
         self.assertEqual(rc, 0)
 
 
+class SlotExpectGuardTest(unittest.TestCase):
+    """--expect compare-and-swap staleness guard (#241)."""
+
+    def test_expect_match_writes(self):
+        from lib.membership_guard import issues_fingerprint
+        track = _track(name="alpha", repo="ok/repo", issues=[10, 20])
+        fp = issues_fingerprint(track.meta)
+        rc, mw, out = _drive(["30", "alpha", f"--expect={fp}"],
+                             tracks=[track], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertIn(30, track.meta["github"]["issues"])
+
+    def test_expect_mismatch_aborts_with_stale_json(self):
+        import json
+        from lib.membership_guard import issues_fingerprint
+        track = _track(name="alpha", repo="ok/repo", issues=[10, 20])
+        stale_fp = issues_fingerprint({"github": {"issues": [10]}})  # what we thought
+        rc, mw, out = _drive(["30", "alpha", f"--expect={stale_fp}"],
+                             tracks=[track], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        data = json.loads(out.strip())  # stdout is pure JSON in --expect mode
+        self.assertTrue(data["stale"])
+        self.assertEqual(data["current"], [10, 20])
+        self.assertEqual(data["track"], "alpha")
+
+    def test_no_expect_never_aborts(self):
+        track = _track(name="alpha", repo="ok/repo", issues=[10, 20])
+        rc, mw, out = _drive(["30", "alpha"], tracks=[track], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+
+    def test_milestone_check_gh_missing_does_not_crash(self):
+        """The advisory `gh issue view` milestone check sits between the rebase
+        guard and the write — if gh is absent (FileNotFoundError) the slot must
+        still complete the write, not crash."""
+        track = _track(name="alpha", repo="ok/repo", issues=[10])
+        cfg = {"notes_root": "/tmp/fake-notes", "repos": {"ok": {"github": "ok/repo"}}}
+        by_path = {str(track.path): track}
+
+        def fake_parse(p):
+            t = by_path[str(p)]
+            return (t.meta, t.body)
+
+        with patch("commands.slot.load_config", return_value=cfg), \
+             patch("commands.slot.discover_tracks", return_value=[track]), \
+             patch("commands.slot.subprocess.run", side_effect=FileNotFoundError("gh")), \
+             patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+             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 = slot.run(["30", "alpha"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()  # write still happens despite the gh crash
+        self.assertIn(30, track.meta["github"]["issues"])
+
+    def test_confirm_then_stale_order(self):
+        """Public repo + valid confirm token + a stale --expect: the confirm gate
+        is satisfied first, then the staleness CAS still aborts at write time."""
+        import json
+        from lib.membership_guard import issues_fingerprint
+        track = _track(name="alpha", repo="ok/repo", issues=[10, 20])
+        tok = make_token("ok/repo", "alpha")
+        stale_fp = issues_fingerprint({"github": {"issues": [10]}})
+        rc, mw, out = _drive(["30", "alpha", f"--confirm={tok}", f"--expect={stale_fp}"],
+                             tracks=[track], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        data = json.loads(out.strip())
+        self.assertTrue(data["stale"])
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -39,11 +39,20 @@ class SlotMoveTest(unittest.TestCase):
         cfg = {"notes_root": "/tmp/fake-notes",
                "repos": {"ok": {"github": "ok/ok"}}}
         gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
+        # Writes go through lib.membership_guard now; return each track's own
+        # meta/body from parse_file so the guard mutates them in place.
+        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.slot.subprocess.run", return_value=gh_proc), \
              patch("commands.slot.load_config", return_value=cfg), \
              patch("commands.slot.discover_tracks", return_value=tracks), \
              patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
-             patch("commands.slot.write_file") as mw:
+             patch("lib.membership_guard.parse_file", side_effect=fake_parse), \
+             patch("lib.membership_guard.write_file") as mw:
             rc = slot.run(args)
         return rc, mw
 

package/skills/work-plan/work_plan.py

@@ -47,6 +47,7 @@ SUBCOMMANDS = {
     "duplicates": "commands.duplicates",
     "coverage": "commands.coverage",
     "canonicalize": "commands.canonicalize",
+    "dedupe-tiers": "commands.dedupe_tiers",
     "hygiene": "commands.hygiene",
     "--hygiene": "commands.hygiene",      # flag-style alias
     "plan-status": "commands.plan_status",
@@ -57,6 +58,7 @@ SUBCOMMANDS = {
     "close-issue": "commands.close_issue",
     "in-progress": "commands.in_progress",
     "export": "commands.export",
+    "which-repo": "commands.which_repo",
     "auth-status": "commands.auth_status",
     "list-open-issues": "commands.list_open_issues",
     "set": "commands.set_field",
@@ -127,8 +129,8 @@ DESCRIPTIONS = [
      "AI-cluster GitHub issues into thematic track files. --limit controls how many issues are shown in the prompt (default 100).",
      "ONE-TIME bulk organization of an unsorted milestone, or after a re-org.",
      "/work-plan group --milestone='v1.0.0 — Public Launch'"),
-    ("auto-triage", "[--repo=<key>] [--apply] [--limit=N]",
-     "AI-assign untracked open issues to existing tracks. Step 1 (no --apply): fetches untracked issues + existing tracks, prints AI prompt. Step 2 (--apply): reads AI's JSON answers and slots each assignment into track frontmatter. Complements `group` (which creates new tracks); `auto-triage` assigns to tracks that already exist. --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. Step 1 (no --apply): fetches untracked issues + existing tracks, prints an AI prompt and writes a per-repo batch file stamped with a batch_id; --json emits that batch (+ prompt + answers path) as one JSON object on stdout for the VS Code viewer instead of the human prompt. --heuristic (#373) skips the LLM entirely: it scores each issue against the candidate tracks using local signals (milestone match, track-label overlap, title/scope keyword overlap), writes the v2 answers file itself (stamped source:\"heuristic\", abstain-first), so suggestions work with no Claude session — lower-trust, but offline. Step 2 (--apply [--repo=<key>]): reads the answers (v2 abstain-first shape preferred — only clear-margin suggestions are slotted; legacy v1 [{track,issues}] still accepted) and slots each assignment into track frontmatter. Complements `group` (which creates new tracks); `auto-triage` assigns to tracks that already exist. --limit controls how many untracked issues are shown (default 100).",
      "Periodically — when new issues have piled up outside the track model. Run /work-plan coverage first to confirm there's a gap worth triaging.",
      "/work-plan auto-triage --repo=myproject"),
     ("reconcile", "<track> | --all | --repo=<key> [--draft] [--yes]",
@@ -147,8 +149,12 @@ DESCRIPTIONS = [
      "Insert a canonical master issue table at the top of a track. The table has a Milestone column and is ordered active-milestone-first (the track's milestone_alignment milestone, then other milestones grouped with a blank divider row, then no-milestone last) so near-term work sits above someday work (#101). Refresh-md then targets ONLY this table, re-deriving it (so the order self-heals) and leaving narrative tables alone. Use --repo=<key> or track@repo to disambiguate; with --all, --repo=<key> scopes to one repo.",
      "ONE-TIME for hand-written tracks with multiple narrative tables, OR after restructuring a track.",
      "/work-plan canonicalize ux-redesign"),
+    ("dedupe-tiers", "[--repo=<key>] [--apply]",
+     "Remove private track copies that a shared twin in a repo's .work-plan/ supersedes (#359). When a track is promoted to the shared tier, the private original under notes_root is sometimes left behind (bulk/manual promotion, or a failed unlink) — discover_tracks then warns 'exists in both shared and private' on every run with no cleanup path. This removes the safe orphans and REFUSES any whose private copy references issue numbers the shared one lacks (no silent data loss; the invariant is issue_refs(private) ⊆ issue_refs(shared)). Covers active and archived tiers. Default is a dry-run report; --apply deletes (auto-committed to notes_root, so undoable).",
+     "When `exists in both shared and private` warnings appear, or after a bulk promote that left private originals behind.",
+     "/work-plan dedupe-tiers --repo=critforge --apply"),
     ("hygiene", "[--yes] [--no-duplicates] [--repo=<key>] [--timeout=N]",
-     "Weekly cleanup wrapper: refresh-md + reconcile + duplicates. With --repo=<key>, steps 1 and 2 scope to that repo; the duplicates step (a global similarity scan) is skipped. --timeout=N sets the gh subprocess timeout for the duplicates step (default 30s).",
+     "Weekly cleanup wrapper: refresh-md + reconcile + dedupe-tiers (report-only) + duplicates. With --repo=<key>, steps 1–3 scope to that repo; the duplicates step (a global similarity scan) is skipped. --timeout=N sets the gh subprocess timeout for the duplicates step (default 30s).",
      "WEEKLY — runs all three hygiene commands in sequence so you don't have to remember each. Use --repo=<key> to clean up one project without touching the others.",
      "/work-plan hygiene --repo=myproject"),
     ("export", "--json",
@@ -167,10 +173,10 @@ DESCRIPTIONS = [
      "Guarded edit of a track's frontmatter fields (status, launch_priority, milestone_alignment, blockers, next_up). Validates field names + status values; blockers/next_up take comma-separated issue numbers. Setting `next_up` here writes ONLY the frontmatter field — for next_up plus a session-log entry (and a body refresh), use `handoff --set-next` instead. Writes into a PUBLIC repo only with a confirm token: without one it prints {needs_confirm, reason, token} and makes no change (the VS Code viewer surfaces that as a modal, then re-invokes with --confirm=<token>).",
      "Programmatic/GUI edits that have no dedicated verb — e.g. the VS Code extension changing a status or blockers list. On the terminal you'll usually use the named verbs instead.",
      "/work-plan set ux-redesign status=parked"),
-    ("set-next-up", "<track | track@repo> (--preset=<name> | --order=a,b,c | --clear) [--repo=<key>] [--confirm=<token>]",
-     "Configure the ranking preset for a track's auto next_up suggestion. --preset sets one of the named presets (flow, priority-driven, backlog) or 'custom' (which requires --order). --order=a,b,c sets a custom comma-separated criterion list (milestone, dependency, priority, recency, aging). --clear reverts to the global or default preset. Writes next_up_order into the track's frontmatter (does NOT touch the next_up issue list). Public-repo gated: without --confirm it prints {needs_confirm, reason, token} and makes no change.",
-     "When you want a track to use a different ranking order than the default (flow). Use priority-driven for pure backlog work with no milestones, backlog to surface oldest stalled issues first.",
-     "/work-plan set-next-up my-track --preset=priority-driven"),
+    ("set-next-up", "<track | track@repo> (--preset=<name> | --order=a,b,c | --clear | --auto=on|off) [--repo=<key>] [--confirm=<token>]",
+     "Configure the ranking preset and/or auto-derivation flag for a track's next_up list. --preset sets one of the named presets (flow, priority-driven, backlog) or 'custom' (which requires --order). --order=a,b,c sets a custom comma-separated criterion list (milestone, dependency, priority, recency, aging). --clear reverts to the global or default preset. --auto=on activates auto-derivation (brief/orient/export derive next-up live via the ranking preset instead of the curated list); --auto=off reverts to the curated list. --auto can be used standalone or combined with --preset/--order/--clear. Writes next_up_order and/or next_up_auto into the track's frontmatter (does NOT touch the next_up issue list). Public-repo gated: without --confirm it prints {needs_confirm, reason, token} and makes no change.",
+     "When you want a track to use a different ranking order than the default (flow), or to activate auto-derivation so the viewer always shows a freshly-ranked list. Use priority-driven for pure backlog work with no milestones, backlog to surface oldest stalled issues first.",
+     "/work-plan set-next-up my-track --preset=priority-driven --auto=on"),
     ("new-track", "<repo> <slug> [--priority=P0..P3] [--milestone=<m>] [--private] [--confirm=<token>]",
      "Create a brand-new track file under notes_root in one headless call. <repo> is either a configured key (e.g. 'myproject') or a bare org/repo slug (e.g. 'your-org/myproject'). Writes frontmatter with status=active and optional priority/milestone. Gates on public repos — prints {needs_confirm, token} and exits cleanly; re-run with --confirm=<token> to proceed.",
      "When a new feature branch or initiative starts and you want the track file created immediately — especially from a non-terminal caller like the VS Code extension that can't interactively run init.",
@@ -219,6 +225,10 @@ DESCRIPTIONS = [
      "Promote a PRIVATE track (local-only, in notes_root) to the repo's SHARED tier and publish it (#306). Moves the track's `.md` into the repo's `.work-plan/` (on its `plan_branch`, via a worktree), removes the private copy so it isn't duplicated, commits to the plan branch, and pushes — unless `--no-push` (keeps it local). The tier is derived from location, so this is a file move, not a frontmatter edit. Requires the repo to have a local clone + a `plan_branch` (else hints `plan-branch init`). Pushing to a PUBLIC repo makes the track world-visible, so the push is confirm-token gated (prints `needs_confirm` + token; re-run with `--confirm=<token>`).",
      "When a private track is ready to share with teammates — promote it to the shared plan branch in one step instead of hand-moving the file.",
      "/work-plan push-track my-feature --repo=myproject"),
+    ("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. Underlies `brief` cwd auto-scope and the VS Code viewer's repo auto-focus.",
+     "Rarely run by hand — it's the shared resolver the viewer and `brief` call. Useful to confirm which repo a checkout maps to.",
+     "/work-plan which-repo --json"),
 ]