@stylusnexus/work-plan 2026.6.16 → 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_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

@@ -129,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]",