@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,243 @@
+"""Tests for the non-interactive slot command (issue #87, Phase 3a).
+
+Covers:
+- Slots a new issue into a private-repo track → write_file called, rc 0.
+- Issue already present → no write, rc 0, prints "already in".
+- Public repo, no token → prints needs_confirm JSON, write_file NOT called, rc 0.
+- Public repo with valid --confirm=<token> → write_file called, rc 0.
+- --move with a prior owner → removes issue from prior owner (two writes).
+- Default / --no-move with a prior owner → prior owner NOT modified (one write)
+  and "still listed … --move" note is printed.
+- Bad issue number / no positional → rc 2.
+- No input() is reached on the non-interactive flagged paths.
+"""
+import io
+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 commands import slot
+from lib.write_guard import make_token
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _track(*, name, repo="ok/repo", issues=None, status="active"):
+    return SimpleNamespace(
+        name=name,
+        path=Path(f"/tmp/fake/{name}.md"),
+        body="# fake",
+        meta={
+            "track": name,
+            "status": status,
+            "github": {"repo": repo, "issues": list(issues or [])},
+        },
+        has_frontmatter=True,
+        repo=repo,
+    )
+
+
+def _drive(args, tracks=None, vis="PRIVATE"):
+    """Run slot.run(args) with all external I/O mocked.
+
+    vis controls what repo_visibility returns (used by needs_confirm).
+    tracks defaults to a single empty private-repo track named 'alpha'.
+    """
+    if tracks is None:
+        tracks = [_track(name="alpha", repo="ok/repo", issues=[])]
+    cfg = {"notes_root": "/tmp/fake-notes", "repos": {"ok": {"github": "ok/repo"}}}
+    gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
+
+    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:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = slot.run(args)
+    return rc, mw, buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+class SlotNonInteractiveTest(unittest.TestCase):
+
+    # ------------------------------------------------------------------
+    # Basic slot (private repo)
+    # ------------------------------------------------------------------
+
+    def test_slots_new_issue_into_private_track(self):
+        """Slots a new issue into a private-repo track → write_file called, rc 0."""
+        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()
+        written_meta = mw.call_args[0][1]
+        self.assertIn(30, written_meta["github"]["issues"])
+        # Issues are sorted
+        self.assertEqual(sorted(written_meta["github"]["issues"]),
+                         written_meta["github"]["issues"])
+
+    def test_already_present_no_write(self):
+        """Issue already present → no write, rc 0, prints 'already in'."""
+        track = _track(name="alpha", repo="ok/repo", issues=[42])
+        rc, mw, out = _drive(["42", "alpha"], tracks=[track], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        self.assertIn("already in", out)
+
+    # ------------------------------------------------------------------
+    # Confirm-token gate (public repo)
+    # ------------------------------------------------------------------
+
+    def test_public_repo_no_token_returns_needs_confirm_json(self):
+        """Public repo, no token → prints needs_confirm JSON, write_file NOT called, rc 0."""
+        import json
+        track = _track(name="alpha", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["99", "alpha"], tracks=[track], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        # Output should be parseable JSON with needs_confirm key
+        data = json.loads(out.strip())
+        self.assertTrue(data["needs_confirm"])
+        self.assertEqual(data["token"], make_token("ok/repo", "alpha"))
+
+    def test_public_repo_unknown_visibility_returns_needs_confirm_json(self):
+        """Unknown visibility (None) → also requires confirm."""
+        import json
+        track = _track(name="alpha", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["99", "alpha"], tracks=[track], vis=None)
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        data = json.loads(out.strip())
+        self.assertTrue(data["needs_confirm"])
+
+    def test_public_repo_with_valid_confirm_performs_write(self):
+        """Public repo with valid --confirm=<token> → write_file called, rc 0."""
+        track = _track(name="alpha", repo="ok/repo", issues=[])
+        tok = make_token("ok/repo", "alpha")
+        rc, mw, out = _drive(["99", "alpha", f"--confirm={tok}"],
+                              tracks=[track], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+
+    def test_public_repo_with_wrong_token_blocks_write(self):
+        """Public repo with wrong confirm token → blocked, no write."""
+        import json
+        track = _track(name="alpha", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["99", "alpha", "--confirm=badtoken"],
+                              tracks=[track], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        data = json.loads(out.strip())
+        self.assertTrue(data["needs_confirm"])
+
+    # ------------------------------------------------------------------
+    # --move / --no-move flags
+    # ------------------------------------------------------------------
+
+    def test_move_flag_removes_issue_from_prior_owner(self):
+        """--move with a prior owner → removes issue from source, writes both."""
+        source = _track(name="alpha", repo="ok/repo", issues=[42])
+        target = _track(name="beta", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["42", "beta", "--move"],
+                              tracks=[source, target], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        self.assertEqual(2, mw.call_count,
+                         "source + target should both be written with --move")
+        self.assertNotIn(42, source.meta["github"]["issues"])
+        self.assertIn(42, target.meta["github"]["issues"])
+
+    def test_default_no_move_preserves_prior_owner(self):
+        """Default (no flags) with a prior owner → prior owner NOT modified; note printed."""
+        source = _track(name="alpha", repo="ok/repo", issues=[42])
+        target = _track(name="beta", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["42", "beta"], tracks=[source, target], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()  # only target written
+        # Source is untouched
+        self.assertIn(42, source.meta["github"]["issues"])
+        self.assertIn(42, target.meta["github"]["issues"])
+        # Note about --move must be printed
+        self.assertIn("--move", out)
+        self.assertIn("alpha", out)
+
+    def test_explicit_no_move_preserves_prior_owner(self):
+        """Explicit --no-move behaves same as default: prior owner NOT modified."""
+        source = _track(name="alpha", repo="ok/repo", issues=[42])
+        target = _track(name="beta", repo="ok/repo", issues=[])
+        rc, mw, out = _drive(["42", "beta", "--no-move"],
+                              tracks=[source, target], vis="PRIVATE")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertIn(42, source.meta["github"]["issues"])
+        self.assertIn(42, target.meta["github"]["issues"])
+        self.assertIn("--move", out)
+
+    # ------------------------------------------------------------------
+    # Error cases
+    # ------------------------------------------------------------------
+
+    def test_no_positional_args_returns_rc2(self):
+        """No positional arguments → rc 2 (usage error)."""
+        rc, mw, out = _drive([])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_bad_issue_number_returns_rc2(self):
+        """Non-integer issue number → rc 2."""
+        rc, mw, out = _drive(["notanumber", "alpha"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    def test_move_and_no_move_together_returns_rc2(self):
+        """Passing both --move and --no-move → rc 2, write_file NOT called."""
+        track = _track(name="alpha", repo="ok/repo", issues=[42])
+        rc, mw, out = _drive(["42", "alpha", "--move", "--no-move"], tracks=[track], vis="PRIVATE")
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+        self.assertIn("ERROR", out)
+        self.assertIn("mutually exclusive", out)
+
+    # ------------------------------------------------------------------
+    # No input() on non-interactive paths
+    # ------------------------------------------------------------------
+
+    def test_no_input_called_on_flagged_paths(self):
+        """Flagged paths (issue + track given) never call input() even if
+        prior owners exist or a public repo is detected."""
+        source = _track(name="alpha", repo="ok/repo", issues=[42])
+        target = _track(name="beta", repo="ok/repo", issues=[])
+
+        def _raise(*a, **kw):
+            raise AssertionError("input() must not be called on non-interactive path")
+
+        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"}}}
+            gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
+            with patch("commands.slot.load_config", return_value=cfg), \
+                 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"):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    # --move (prior owner path) + private repo (no confirm gate)
+                    rc = slot.run(["42", "beta", "--move"])
+        self.assertEqual(rc, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,128 @@
+"""Tests for slot's prior-ownership detection (issue #62).
+
+Before #62, `slot` was add-only — running `slot 4562 chat-nlu` while #4562 was
+already listed in `ai-generators.md` frontmatter would leave the issue in BOTH
+tracks. The only fix was hand-editing YAML, which SKILL.md explicitly warns
+against. These tests pin the non-interactive behavior introduced in #87:
+detect prior ownership, and move only on explicit --move so non-interactive
+runs preserve add-only semantics by default.
+"""
+import sys
+import unittest
+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 commands import slot
+
+
+def _track(*, name, repo, issues, status="active"):
+    return SimpleNamespace(
+        name=name,
+        path=Path(f"/tmp/fake/{name}.md"),
+        body="# fake",
+        meta={
+            "track": name,
+            "status": status,
+            "github": {"repo": repo, "issues": list(issues)},
+        },
+        has_frontmatter=True,
+        repo=repo,
+    )
+
+
+class SlotMoveTest(unittest.TestCase):
+    def _drive(self, *, tracks, args):
+        cfg = {"notes_root": "/tmp/fake-notes",
+               "repos": {"ok": {"github": "ok/ok"}}}
+        gh_proc = MagicMock(returncode=0, stdout="{}", stderr="")
+        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:
+            rc = slot.run(args)
+        return rc, mw
+
+    def test_no_prior_ownership_writes_only_target(self):
+        target = _track(name="alpha", repo="ok/ok", issues=[])
+        rc, mw = self._drive(tracks=[target], args=["100", "alpha"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertEqual(100, target.meta["github"]["issues"][0])
+
+    def test_prior_ownership_with_move_flag_removes_from_source(self):
+        source = _track(name="alpha", repo="ok/ok", issues=[42])
+        target = _track(name="beta", repo="ok/ok", issues=[])
+        rc, mw = self._drive(
+            tracks=[source, target], args=["42", "beta", "--move"],
+        )
+        self.assertEqual(rc, 0)
+        self.assertEqual(2, mw.call_count, "source + target should both be written")
+        self.assertEqual([], source.meta["github"]["issues"])
+        self.assertEqual([42], target.meta["github"]["issues"])
+
+    def test_prior_ownership_without_move_flag_preserves_add_only(self):
+        # Default (no --move flag) → pre-#62 behavior: target gets the issue,
+        # source is untouched (duplicated state that reconcile can later FLAG).
+        source = _track(name="alpha", repo="ok/ok", issues=[42])
+        target = _track(name="beta", repo="ok/ok", issues=[])
+        rc, mw = self._drive(
+            tracks=[source, target], args=["42", "beta"],
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertEqual([42], source.meta["github"]["issues"])
+        self.assertEqual([42], target.meta["github"]["issues"])
+
+    def test_explicit_no_move_flag_preserves_add_only(self):
+        # --no-move behaves identically to the default.
+        source = _track(name="alpha", repo="ok/ok", issues=[42])
+        target = _track(name="beta", repo="ok/ok", issues=[])
+        rc, mw = self._drive(
+            tracks=[source, target], args=["42", "beta", "--no-move"],
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertEqual([42], source.meta["github"]["issues"])
+
+    def test_already_in_target_short_circuits(self):
+        # Issue already listed in target → no write.
+        source = _track(name="alpha", repo="ok/ok", issues=[42])
+        target = _track(name="beta", repo="ok/ok", issues=[42])
+        rc, mw = self._drive(
+            tracks=[source, target], args=["42", "beta"],
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+
+    def test_cross_repo_issue_not_detected_as_prior_owner(self):
+        # Same number in a different repo is a different issue. The prior-
+        # owner sweep MUST filter by track.repo or it will spuriously offer
+        # to move unrelated issues across repos.
+        other_repo = _track(name="alpha", repo="other/repo", issues=[42])
+        target = _track(name="beta", repo="ok/ok", issues=[])
+        rc, mw = self._drive(
+            tracks=[other_repo, target], args=["42", "beta"],
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertEqual([42], other_repo.meta["github"]["issues"])
+
+    def test_inactive_source_not_detected_as_prior_owner(self):
+        # Archived/parked tracks shouldn't be candidates — moving FROM a
+        # closed track is the wrong mental model; that's a reopen, not a slot.
+        parked = _track(name="alpha", repo="ok/ok", issues=[42], status="parked")
+        target = _track(name="beta", repo="ok/ok", issues=[])
+        rc, mw = self._drive(
+            tracks=[parked, target], args=["42", "beta"],
+        )
+        self.assertEqual(rc, 0)
+        self.assertEqual([42], parked.meta["github"]["issues"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,46 @@
+"""Smoke test: importable + main() exists."""
+import io
+import unittest
+import sys
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+import work_plan
+
+
+class SmokeTest(unittest.TestCase):
+    def test_main_exists(self):
+        self.assertTrue(callable(work_plan.main))
+
+    def test_main_no_args_returns_2(self):
+        self.assertEqual(work_plan.main(["work_plan.py"]), 2)
+
+    def test_version_loads_from_file(self):
+        # VERSION lives at the repo root in source mode and next to work_plan.py
+        # in installed mode. The loader walks upward; either layout must produce
+        # a non-empty string. Guards against future moves of the VERSION file.
+        v = work_plan._load_version()
+        self.assertTrue(v, "VERSION file unreachable from work_plan.py")
+        self.assertNotEqual(v, "unknown",
+                            "VERSION file present but resolved to 'unknown' fallback")
+
+    def test_version_flag_prints_and_exits_zero(self):
+        for flag in ("--version", "-v"):
+            with self.subTest(flag=flag):
+                out_buf = io.StringIO()
+                err_buf = io.StringIO()
+                with redirect_stdout(out_buf), redirect_stderr(err_buf):
+                    rc = work_plan.main(["work_plan.py", flag])
+                out = out_buf.getvalue().strip()
+                err = err_buf.getvalue()
+                self.assertEqual(rc, 0)
+                self.assertTrue(out, f"{flag} produced empty stdout")
+                self.assertIn(work_plan.VERSION, out)
+                self.assertEqual(err, "", f"{flag} wrote to stderr: {err!r}")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,79 @@
+"""Tests for idempotent status-header stamping."""
+import unittest
+import sys
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.status_header import BEGIN, END, render_block, stamp
+
+ROW = {
+    "glyph": "✅", "verdict": "shipped",
+    "files_present": 9, "files_declared": 9,
+    "last_touched": "2026-04-02",
+}
+
+
+class RenderBlockTest(unittest.TestCase):
+    def test_block_is_delimited_and_evidence_only(self):
+        block = render_block(ROW)
+        self.assertTrue(block.startswith(BEGIN))
+        self.assertTrue(block.rstrip().endswith(END))
+        self.assertIn("shipped", block)
+        self.assertIn("9/9 files", block)
+        self.assertIn("2026-04-02", block)
+
+    def test_none_last_touched_renders_unknown(self):
+        row = dict(ROW, last_touched=None)
+        self.assertIn("unknown", render_block(row))
+
+
+class StampTest(unittest.TestCase):
+    DOC = "# My Plan\n\nSome body text.\n"
+
+    def test_inserts_after_h1(self):
+        out = stamp(self.DOC, ROW)
+        self.assertIn(BEGIN, out)
+        self.assertLess(out.index(BEGIN), out.index("Some body text."))
+        self.assertGreater(out.index(BEGIN), out.index("# My Plan"))
+
+    def test_idempotent_same_evidence_zero_diff(self):
+        once = stamp(self.DOC, ROW)
+        twice = stamp(once, ROW)
+        self.assertEqual(once, twice)
+
+    def test_rewrites_only_block_on_evidence_change(self):
+        once = stamp(self.DOC, ROW)
+        changed = stamp(once, dict(ROW, files_present=5, verdict="partial"))
+        self.assertNotEqual(once, changed)
+        self.assertEqual(changed.count(BEGIN), 1)
+        self.assertIn("partial", changed)
+        self.assertNotIn("shipped", changed)
+
+    def test_prepends_when_no_h1(self):
+        out = stamp("no heading here\n", ROW)
+        self.assertTrue(out.startswith(BEGIN))
+
+    def test_duplicate_blocks_collapse_to_one_fresh(self):
+        # Two stale blocks (e.g. from a bad merge) -> one fresh, no stale leftover.
+        block = render_block(dict(ROW, verdict="partial", files_present=1))
+        doc = f"# Plan\n\n{block}\n\nbody\n\n{block}\n"
+        out = stamp(doc, ROW)
+        self.assertEqual(out.count(BEGIN), 1)
+        self.assertEqual(out.count(END), 1)
+        self.assertIn("shipped", out)
+        self.assertNotIn("partial", out)
+        self.assertEqual(out, stamp(out, ROW))   # stable on re-run
+
+    def test_dangling_begin_does_not_duplicate(self):
+        # An orphan BEGIN (no END) must not cause a second block to be stacked.
+        doc = f"# Plan\n\n{BEGIN}\n> **Status:** truncated\n\nbody\n"
+        out = stamp(doc, ROW)
+        self.assertEqual(out.count(BEGIN), 1)
+        self.assertEqual(out.count(END), 1)
+        self.assertEqual(out, stamp(out, ROW))   # idempotent afterward
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,162 @@
+"""Tests for status_table parser/updater."""
+import unittest
+import sys
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.status_table import (
+    find_status_table, update_row_status, ISSUE_NUM_RE,
+    render_issue_row, append_rows, sync_missing_rows,
+    find_canonical_status_tables, CANONICAL_MARKER,
+)
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def _canonical_body(rows):
+    """Build a body with a canonical issue table containing the given rows.
+
+    `rows` is a list of pre-rendered row strings (without leading/trailing
+    newline). A trailing narrative section is included to prove appends land
+    before it, not at end-of-body.
+    """
+    lines = [
+        "## Issues (canonical)",
+        "",
+        f"{CANONICAL_MARKER} — auto-managed. -->",
+        "",
+        "| # | Title | Assignee | Status |",
+        "|---|---|---|---|",
+    ]
+    lines.extend(rows)
+    lines.extend(["", "---", "", "## Notes", "", "Some narrative here."])
+    return "\n".join(lines)
+
+
+class FindStatusTableTest(unittest.TestCase):
+    def test_finds_table_with_status_col(self):
+        body = (FIXTURES / "with_status_table.md").read_text()
+        table = find_status_table(body)
+        self.assertIsNotNone(table)
+        self.assertEqual(table["status_col_index"], 2)
+        self.assertEqual(len(table["rows"]), 3)
+
+    def test_returns_none_when_no_status_table(self):
+        self.assertIsNone(find_status_table("# Just text"))
+
+
+class UpdateRowStatusTest(unittest.TestCase):
+    def test_updates_one_row(self):
+        body = (FIXTURES / "with_status_table.md").read_text()
+        new = update_row_status(body, 4254, "✅ Shipped (PR #9999)")
+        self.assertIn("✅ Shipped (PR #9999)", new)
+        self.assertIn("✅ Shipped ", new)
+
+
+class RenderIssueRowTest(unittest.TestCase):
+    def test_renders_canonical_row_shape(self):
+        row = render_issue_row(487, "fix the thing", "@alice", "🔲 Open")
+        self.assertEqual(row, "| #487 | fix the thing | @alice | 🔲 Open |")
+
+
+class AppendRowsTest(unittest.TestCase):
+    def test_inserts_after_last_row_before_narrative(self):
+        body = _canonical_body(["| #678 | a | — | 🔲 Open |"])
+        table = find_canonical_status_tables(body)[0]
+        new = append_rows(body, table, ["| #999 | b | — | 🔲 Open |"])
+        lines = new.split("\n")
+        # New row sits directly after the existing data row...
+        self.assertEqual(lines[7], "| #999 | b | — | 🔲 Open |")
+        # ...and the narrative section survives below it.
+        self.assertIn("## Notes", new)
+        self.assertLess(new.index("#999"), new.index("## Notes"))
+
+    def test_no_rows_is_noop(self):
+        body = _canonical_body(["| #678 | a | — | 🔲 Open |"])
+        table = find_canonical_status_tables(body)[0]
+        self.assertEqual(append_rows(body, table, []), body)
+
+
+class SyncMissingRowsTest(unittest.TestCase):
+    def test_appends_missing_in_frontmatter_order(self):
+        body = _canonical_body([
+            "| #678 | first | — | 🔲 Open |",
+            "| #925 | second | — | ✅ Shipped |",
+        ])
+        # Frontmatter lists three more than the table, deliberately out of
+        # numeric order to prove frontmatter order (not sort) is honored.
+        frontmatter_nums = [678, 925, 5195, 487, 2196]
+        issues_by_num = {
+            5195: {"number": 5195, "title": "newer", "state": "OPEN",
+                   "assignees": [{"login": "bob"}]},
+            487: {"number": 487, "title": "older", "state": "CLOSED", "assignees": []},
+            2196: {"number": 2196, "title": "mid", "state": "OPEN", "assignees": []},
+        }
+        new, added = sync_missing_rows(body, frontmatter_nums, issues_by_num)
+        self.assertEqual(added, 3)
+        table = find_canonical_status_tables(new)[0]
+        nums = [int(ISSUE_NUM_RE.search(r["cells"][0]).group(1)) for r in table["rows"]]
+        self.assertEqual(nums, [678, 925, 5195, 487, 2196])
+        self.assertIn("| #5195 | newer | @bob | 🔲 Open |", new)
+        self.assertIn("| #487 | older | — | ✅ Shipped |", new)
+
+    def test_slots_low_rank_row_above_existing(self):
+        # The #79 case: frontmatter lists #487 first, but it's missing from a
+        # table whose existing rows start at #678. Option A slots #487 to the
+        # top instead of tacking it onto the end.
+        body = _canonical_body([
+            "| #678 | first | — | 🔲 Open |",
+            "| #2528 | last | — | ✅ Shipped |",
+        ])
+        frontmatter_nums = [487, 678, 1556, 2528, 5195]
+        issues_by_num = {
+            487: {"number": 487, "title": "earliest", "state": "OPEN", "assignees": []},
+            1556: {"number": 1556, "title": "middle", "state": "OPEN", "assignees": []},
+            5195: {"number": 5195, "title": "newest", "state": "OPEN", "assignees": []},
+        }
+        new, added = sync_missing_rows(body, frontmatter_nums, issues_by_num)
+        self.assertEqual(added, 3)
+        table = find_canonical_status_tables(new)[0]
+        nums = [int(ISSUE_NUM_RE.search(r["cells"][0]).group(1)) for r in table["rows"]]
+        # Full table order now mirrors frontmatter: #487 at top, #1556 between
+        # #678 and #2528, #5195 at the end.
+        self.assertEqual(nums, frontmatter_nums)
+        # Existing rows are re-emitted verbatim (minimal diff).
+        self.assertIn("| #678 | first | — | 🔲 Open |", new)
+        self.assertIn("| #2528 | last | — | ✅ Shipped |", new)
+
+    def test_unranked_existing_row_imposes_no_constraint(self):
+        # A row whose issue isn't in frontmatter (manual addition) shouldn't
+        # block a missing row from slotting past it.
+        body = _canonical_body([
+            "| #9001 | manual | — | 🔲 Open |",
+            "| #678 | tracked | — | 🔲 Open |",
+        ])
+        new, added = sync_missing_rows(
+            body, [487, 678],
+            {487: {"number": 487, "title": "early", "state": "OPEN", "assignees": []}},
+        )
+        self.assertEqual(added, 1)
+        table = find_canonical_status_tables(new)[0]
+        nums = [int(ISSUE_NUM_RE.search(r["cells"][0]).group(1)) for r in table["rows"]]
+        # #487 slots immediately before #678 (its frontmatter successor),
+        # leaving the unranked #9001 put.
+        self.assertEqual(nums, [9001, 487, 678])
+
+    def test_no_drift_is_noop(self):
+        body = _canonical_body(["| #678 | first | — | 🔲 Open |"])
+        new, added = sync_missing_rows(body, [678], {678: {"number": 678}})
+        self.assertEqual(added, 0)
+        self.assertEqual(new, body)
+
+    def test_missing_issue_without_fetched_data_still_appends(self):
+        body = _canonical_body(["| #678 | first | — | 🔲 Open |"])
+        new, added = sync_missing_rows(body, [678, 999], {})
+        self.assertEqual(added, 1)
+        self.assertIn("#999", new)
+
+
+if __name__ == "__main__":
+    unittest.main()