@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,149 @@
+"""Tests for the next_up suggestion algorithm.
+
+Covers the priority + recency sort, blocker exclusion, closed-issue filter,
+top-N capping, and the `updatedAt`-missing fallback. The algorithm has one
+home (lib/next_up.py) shared by handoff's --auto-next flag and brief's
+next_up_auto: true frontmatter knob — so a regression here would surface
+in both commands.
+"""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.next_up import suggest_next_up
+
+
+def _issue(num, *, state="OPEN", priority=None, updated="2026-01-01T00:00:00Z",
+           title="", milestone=None):
+    """Build a minimal issue dict matching gh's --json output."""
+    labels = [{"name": f"priority/{priority}"}] if priority else []
+    ms_obj = {"title": milestone} if milestone else None
+    return {
+        "number": num, "state": state, "labels": labels,
+        "updatedAt": updated, "title": title or f"issue #{num}",
+        "milestone": ms_obj,
+    }
+
+
+class SuggestNextUpTest(unittest.TestCase):
+    def test_empty_input_returns_empty(self):
+        self.assertEqual(suggest_next_up([], []), [])
+
+    def test_only_closed_returns_empty(self):
+        issues = [_issue(1, state="CLOSED", priority="P0"),
+                  _issue(2, state="CLOSED", priority="P1")]
+        self.assertEqual(suggest_next_up(issues, []), [])
+
+    def test_priority_order(self):
+        # Same updatedAt across all — pure priority ranking. P0 < P1 < P2 < P3.
+        issues = [
+            _issue(3, priority="P3"),
+            _issue(0, priority="P0"),
+            _issue(2, priority="P2"),
+            _issue(1, priority="P1"),
+        ]
+        self.assertEqual(suggest_next_up(issues, []), [0, 1, 2])  # default n=3
+
+    def test_recency_within_priority_bucket(self):
+        # All P1 — most recently updated wins.
+        issues = [
+            _issue(10, priority="P1", updated="2026-01-01T00:00:00Z"),
+            _issue(20, priority="P1", updated="2026-04-30T00:00:00Z"),  # newest
+            _issue(30, priority="P1", updated="2026-02-15T00:00:00Z"),
+        ]
+        self.assertEqual(suggest_next_up(issues, []), [20, 30, 10])
+
+    def test_priority_dominates_recency(self):
+        # P0 is older than P3 but still comes first.
+        issues = [
+            _issue(99, priority="P3", updated="2026-04-30T00:00:00Z"),
+            _issue(1, priority="P0", updated="2024-01-01T00:00:00Z"),
+        ]
+        self.assertEqual(suggest_next_up(issues, []), [1, 99])
+
+    def test_no_priority_label_defaults_to_p3(self):
+        # Unlabeled issues sort with P3, behind P0/P1/P2.
+        issues = [
+            _issue(50, priority=None, updated="2026-04-30T00:00:00Z"),
+            _issue(51, priority="P3", updated="2026-04-30T00:00:00Z"),
+            _issue(2, priority="P2"),
+        ]
+        result = suggest_next_up(issues, [])
+        # P2 first; the two P3 (one labeled, one defaulting) follow.
+        self.assertEqual(result[0], 2)
+        self.assertIn(50, result[1:])
+        self.assertIn(51, result[1:])
+
+    def test_blockers_excluded(self):
+        issues = [
+            _issue(1, priority="P0"),
+            _issue(2, priority="P1"),
+            _issue(3, priority="P2"),
+        ]
+        # #1 is blocked — should NOT appear, even though it's P0.
+        self.assertEqual(suggest_next_up(issues, [1]), [2, 3])
+
+    def test_top_n_caps_result(self):
+        issues = [_issue(i, priority="P0") for i in range(10)]
+        self.assertEqual(len(suggest_next_up(issues, [], n=2)), 2)
+        self.assertEqual(len(suggest_next_up(issues, [], n=5)), 5)
+
+    def test_default_n_is_3(self):
+        issues = [_issue(i, priority="P0") for i in range(10)]
+        self.assertEqual(len(suggest_next_up(issues, [])), 3)
+
+    def test_missing_updatedAt_treated_as_oldest(self):
+        # Within same priority, an issue without updatedAt should sort LAST.
+        issues = [
+            _issue(1, priority="P1", updated="2026-01-01T00:00:00Z"),
+            _issue(2, priority="P1", updated=""),  # missing
+            _issue(3, priority="P1", updated="2026-04-30T00:00:00Z"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertEqual(result[0], 3)  # newest first
+        self.assertEqual(result[-1], 2)  # missing-updated last
+
+    def test_track_milestone_aligned_outranks_other_milestone(self):
+        # Track is gated by v0.4.0. A P0 on v2.0.0 must sort BEHIND a P3 on v0.4.0
+        # because milestone alignment dominates priority — keeps post-launch
+        # work from polluting a launch-window auto-next.
+        issues = [
+            _issue(1, priority="P0", milestone="v2.0.0 — Post-Launch",
+                   updated="2026-04-30T00:00:00Z"),
+            _issue(2, priority="P3", milestone="v0.4.0 — MVP",
+                   updated="2026-01-01T00:00:00Z"),
+        ]
+        self.assertEqual(suggest_next_up(issues, [], track_milestone="v0.4.0"), [2, 1])
+
+    def test_track_milestone_unmilestoned_sorts_last(self):
+        # Items with no milestone fall behind any milestoned item.
+        issues = [
+            _issue(1, priority="P0", milestone=None),
+            _issue(2, priority="P3", milestone="v2.0.0"),
+        ]
+        self.assertEqual(suggest_next_up(issues, [], track_milestone="v0.4.0"), [2, 1])
+
+    def test_no_track_milestone_preserves_priority_order(self):
+        # Without a track milestone, behavior matches the legacy priority+recency sort:
+        # all milestone buckets collapse to "OTHER" so they tie, leaving priority to decide.
+        issues = [
+            _issue(1, priority="P0", milestone="v2.0.0"),
+            _issue(2, priority="P3", milestone="v0.4.0"),
+        ]
+        self.assertEqual(suggest_next_up(issues, []), [1, 2])
+
+    def test_unparsable_updatedAt_falls_back_gracefully(self):
+        # A garbage timestamp string should be treated like missing — not crash.
+        issues = [
+            _issue(1, priority="P0", updated="not-a-date"),
+            _issue(2, priority="P0", updated="2026-04-30T00:00:00Z"),
+        ]
+        result = suggest_next_up(issues, [])
+        self.assertEqual(result, [2, 1])  # parsable+newer wins; garbage trails
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,78 @@
+"""Tests for lib/notes_readme.py — seed_readme."""
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.notes_readme import seed_readme, README_CONTENT
+
+
+class SeedReadmeTest(unittest.TestCase):
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.work_plan_dir = Path(self._tmp.name) / ".work-plan"
+        self.work_plan_dir.mkdir()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_writes_readme_when_absent_returns_true(self):
+        """seed_readme writes README.md when it doesn't exist; returns True."""
+        result = seed_readme(self.work_plan_dir)
+        self.assertTrue(result)
+        readme = self.work_plan_dir / "README.md"
+        self.assertTrue(readme.exists())
+
+    def test_idempotent_existing_readme_returns_false(self):
+        """seed_readme skips when README.md already exists; returns False."""
+        readme = self.work_plan_dir / "README.md"
+        readme.write_text("existing content", encoding="utf-8")
+        result = seed_readme(self.work_plan_dir)
+        self.assertFalse(result)
+        # Content not overwritten
+        self.assertEqual(readme.read_text(encoding="utf-8"), "existing content")
+
+    def test_idempotent_second_call_returns_false(self):
+        """Calling seed_readme twice: first call True, second call False."""
+        first = seed_readme(self.work_plan_dir)
+        second = seed_readme(self.work_plan_dir)
+        self.assertTrue(first)
+        self.assertFalse(second)
+
+    def test_readme_content_contains_shared_tier(self):
+        """Written README contains 'shared tier'."""
+        seed_readme(self.work_plan_dir)
+        content = (self.work_plan_dir / "README.md").read_text(encoding="utf-8")
+        self.assertIn("shared tier", content)
+
+    def test_readme_content_contains_private_flag(self):
+        """Written README mentions '--private'."""
+        seed_readme(self.work_plan_dir)
+        content = (self.work_plan_dir / "README.md").read_text(encoding="utf-8")
+        self.assertIn("--private", content)
+
+    def test_readme_content_contains_work_plan_toolkit(self):
+        """Written README references 'work-plan-toolkit'."""
+        seed_readme(self.work_plan_dir)
+        content = (self.work_plan_dir / "README.md").read_text(encoding="utf-8")
+        self.assertIn("work-plan-toolkit", content)
+
+    def test_absent_readme_in_existing_folder_is_written(self):
+        """Caller's responsibility: seed_readme writes when README absent,
+        regardless of whether the dir is 'new' or 'existing'.
+        (The deletion-as-opt-out contract is enforced by callers who only
+        call seed_readme when creating a new directory, not by the function.)
+        """
+        # Simulate an existing dir that lost its README (from the function's POV,
+        # the file is just absent → it writes)
+        result = seed_readme(self.work_plan_dir)
+        self.assertTrue(result)
+        self.assertTrue((self.work_plan_dir / "README.md").exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,68 @@
+"""Smoke + behavior test for the plan-status command (offline)."""
+import io
+import json
+import unittest
+import sys
+import tempfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+PLAN_BODY = (
+    "# Idea Mode Implementation Plan\n\n"
+    "**Files:**\n"
+    "- Create: `src/new.ts`\n"
+    "- Create: `src/missing.ts`\n"
+    "- [ ] Step 1: do the thing\n"
+    "- [ ] Step 2: do the other thing\n"
+)
+
+
+class PlanStatusRunTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/superpowers/plans").mkdir(parents=True)
+        (root / "docs/superpowers/plans/2026-03-16-idea-mode-ui.md").write_text(PLAN_BODY)
+        (root / "src").mkdir()
+        (root / "src/new.ts").write_text("export const x = 1")  # 1 of 2 created
+        return root
+
+    def test_json_report_classifies_partial(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                            return_value=None), \
+                 mock.patch("commands.plan_status.Path.cwd", return_value=root):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = plan_status.run(["--json"])
+            self.assertEqual(rc, 0)
+            data = json.loads(buf.getvalue())
+            self.assertEqual(len(data["docs"]), 1)
+            row = data["docs"][0]
+            self.assertEqual(row["files_present"], 1)
+            self.assertEqual(row["files_declared"], 2)
+            self.assertEqual(row["verdict"], "partial")  # 50% -> partial
+
+    def test_human_report_runs(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                            return_value=None), \
+                 mock.patch("commands.plan_status.Path.cwd", return_value=root):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = plan_status.run([])
+            self.assertEqual(rc, 0)
+            out = buf.getvalue()
+            self.assertIn("plan-status", out)
+            self.assertIn("partial", out)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,61 @@
+"""--archive: previews under --draft; gated by confirmation otherwise (offline)."""
+import io
+import unittest
+import sys
+import tempfile
+from datetime import datetime
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+DEAD_PLAN = "# Dead Plan\n\n- Create: `src/never.ts`\n"
+
+
+class ArchiveTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/superpowers/plans").mkdir(parents=True)
+        self.rel = "docs/superpowers/plans/2026-01-01-dead.md"
+        (root / self.rel).write_text(DEAD_PLAN)
+        return root
+
+    def _run(self, root, args, mv_ok=True):
+        # stale last-commit (well beyond DEAD_DAYS) so the absent-file plan is dead
+        with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                        return_value=datetime(2026, 1, 1)), \
+             mock.patch("commands.plan_status.Path.cwd", return_value=root), \
+             mock.patch("commands.plan_status.git_state.git_mv",
+                        return_value=mv_ok) as mv, \
+             mock.patch("commands.plan_status.prompt_yes_no", return_value=True):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = plan_status.run(args)
+        return rc, buf.getvalue(), mv
+
+    def test_draft_previews_without_moving(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            rc, out, mv = self._run(root, ["--archive", "--draft"])
+            self.assertEqual(rc, 0)
+            self.assertIn("archive", out.lower())
+            mv.assert_not_called()
+
+    def test_apply_moves_after_confirm(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            rc, out, mv = self._run(root, ["--archive"])
+            self.assertEqual(rc, 0)
+            mv.assert_called_once()
+            args = mv.call_args[0]
+            self.assertEqual(args[0], self.rel)
+            self.assertEqual(args[1],
+                             "docs/superpowers/plans/archive/abandoned/2026-01-01-dead.md")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,55 @@
+"""A plan whose declared files live outside the repo -> foreign verdict."""
+import io
+import json
+import unittest
+import sys
+import tempfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+# All declared paths are ~/-rooted -> outside this repo.
+FOREIGN_PLAN = (
+    "# Daily Work Planner\n\n"
+    "- Create: `~/.claude/skills/work-plan/work_plan.py`\n"
+    "- Create: `~/.claude/skills/work-plan/SKILL.md`\n"
+)
+# Declares in-repo src/ paths -> a real (partial) plan, NOT foreign.
+LOCAL_PLAN = "# Real\n\n- Create: `src/here.ts`\n- Create: `src/gone.ts`\n"
+
+
+class ForeignTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/superpowers/plans").mkdir(parents=True)
+        (root / "docs/superpowers/plans/2026-04-28-daily-work-planner.md").write_text(FOREIGN_PLAN)
+        (root / "docs/superpowers/plans/2026-05-01-real.md").write_text(LOCAL_PLAN)
+        (root / "src").mkdir()
+        (root / "src/here.ts").write_text("x")
+        return root
+
+    def _json(self, root):
+        with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                        return_value=None), \
+             mock.patch("commands.plan_status.Path.cwd", return_value=root):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                plan_status.run(["--json"])
+        return {r["rel"].split("/")[-1]: r for r in json.loads(buf.getvalue())["docs"]}
+
+    def test_out_of_tree_plan_is_foreign_local_is_not(self):
+        with tempfile.TemporaryDirectory() as d:
+            rows = self._json(self._repo(d))
+            self.assertEqual(rows["2026-04-28-daily-work-planner.md"]["verdict"], "foreign")
+            self.assertEqual(rows["2026-04-28-daily-work-planner.md"]["glyph"], "🧳")
+            # the in-repo plan is partial (1/2), not foreign
+            self.assertEqual(rows["2026-05-01-real.md"]["verdict"], "partial")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,61 @@
+"""--issues: previews under --draft; opens gh issues after confirm (offline)."""
+import io
+import unittest
+import sys
+import tempfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+# 1 of 2 files present -> partial.
+PARTIAL_PLAN = "# Partial\n\n- Create: `src/here.ts`\n- Create: `src/gone.ts`\n"
+
+
+class IssuesTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/superpowers/plans").mkdir(parents=True)
+        (root / "docs/superpowers/plans/2026-05-01-partial.md").write_text(PARTIAL_PLAN)
+        (root / "src").mkdir()
+        (root / "src/here.ts").write_text("x")   # gone.ts absent -> partial
+        return root
+
+    def _run(self, root, args, create_ret="https://github.com/o/r/issues/9"):
+        with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                        return_value=None), \
+             mock.patch("commands.plan_status._resolve_repo_root", return_value=root), \
+             mock.patch("commands.plan_status._repo_slug", return_value="o/r"), \
+             mock.patch("commands.plan_status.github_state.create_issue",
+                        return_value=create_ret) as ci, \
+             mock.patch("commands.plan_status.prompt_yes_no", return_value=True):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = plan_status.run(args)
+        return rc, buf.getvalue(), ci
+
+    def test_draft_previews_without_creating(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            rc, out, ci = self._run(root, ["--issues", "--draft", "--repo=critforge"])
+            self.assertEqual(rc, 0)
+            self.assertIn("gone.ts", out)       # unsatisfied path shown in preview
+            ci.assert_not_called()
+
+    def test_apply_creates_issue_after_confirm(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            rc, out, ci = self._run(root, ["--issues", "--repo=critforge"])
+            self.assertEqual(rc, 0)
+            ci.assert_called_once()
+            title, body = ci.call_args[0][1], ci.call_args[0][2]
+            self.assertIn("partial", body.lower())
+            self.assertIn("src/gone.ts", body)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,71 @@
+"""--llm --apply: validates provenance, merges verdicts, optionally stamps."""
+import io
+import json
+import unittest
+import sys
+import tempfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+PROSE = "# Design Doc\n\nProse only.\n"
+
+
+class LlmApplyTest(unittest.TestCase):
+    def _setup(self, d, cache, answers):
+        root = Path(d)
+        (root / "docs/superpowers/specs").mkdir(parents=True)
+        rel = "docs/superpowers/specs/2026-03-16-x-design.md"
+        (root / rel).write_text(PROSE)
+        batch = {"repo_root": str(root), "docs": [{"rel": rel}]}
+        (Path(cache) / "plan_status.json").write_text(json.dumps(batch))
+        (Path(cache) / "plan_status.answers.json").write_text(json.dumps(answers))
+        return root, rel
+
+    def _run(self, root, cache, args):
+        with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                        return_value=None), \
+             mock.patch("commands.plan_status.Path.cwd", return_value=root), \
+             mock.patch("commands.plan_status.cache_dir", return_value=Path(cache)):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = plan_status.run(args)
+        return rc, buf.getvalue()
+
+    def test_merges_verdict_into_report(self):
+        with tempfile.TemporaryDirectory() as d, tempfile.TemporaryDirectory() as cache:
+            rel = "docs/superpowers/specs/2026-03-16-x-design.md"
+            root, _ = self._setup(d, cache, [
+                {"rel": rel, "verdict": "shipped", "confidence": 0.9, "rationale": "done"}
+            ])
+            rc, out = self._run(root, cache, ["--llm", "--apply"])
+            self.assertEqual(rc, 0)
+            self.assertIn("shipped", out)
+            self.assertIn("done", out)
+
+    def test_rejects_rel_not_in_batch(self):
+        with tempfile.TemporaryDirectory() as d, tempfile.TemporaryDirectory() as cache:
+            root, rel = self._setup(d, cache, [
+                {"rel": "../evil.md", "verdict": "shipped", "confidence": 1, "rationale": "x"}
+            ])
+            rc, out = self._run(root, cache, ["--llm", "--apply"])
+            self.assertIn("skip", out.lower())
+
+    def test_rejects_repo_root_mismatch(self):
+        with tempfile.TemporaryDirectory() as d, tempfile.TemporaryDirectory() as cache:
+            root, rel = self._setup(d, cache, [])
+            bp = Path(cache) / "plan_status.json"
+            b = json.loads(bp.read_text()); b["repo_root"] = "/somewhere/else"
+            bp.write_text(json.dumps(b))
+            rc, out = self._run(root, cache, ["--llm", "--apply"])
+            self.assertEqual(rc, 1)
+            self.assertIn("repo_root", out.lower())
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,66 @@
+"""--llm step 1: writes a batch of candidate docs + prints a prompt."""
+import io
+import json
+import unittest
+import sys
+import tempfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import plan_status
+
+PROSE = "# Design Doc\n\nProse only, no file manifest here.\n"
+
+
+class LlmPrepareTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/superpowers/specs").mkdir(parents=True)
+        (root / "docs/superpowers/specs/2026-03-16-x-design.md").write_text(PROSE)
+        return root
+
+    def test_prepare_writes_batch_of_candidates(self):
+        with tempfile.TemporaryDirectory() as d, tempfile.TemporaryDirectory() as cache:
+            root = self._repo(d)
+            cache_file = Path(cache) / "plan_status.json"
+            with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                            return_value=None), \
+                 mock.patch("commands.plan_status.Path.cwd", return_value=root), \
+                 mock.patch("commands.plan_status.cache_dir", return_value=Path(cache)):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = plan_status.run(["--llm"])
+            self.assertEqual(rc, 0)
+            self.assertTrue(cache_file.exists())
+            batch = json.loads(cache_file.read_text())
+            self.assertEqual(batch["repo_root"], str(root))
+            rels = [d["rel"] for d in batch["docs"]]
+            self.assertIn("docs/superpowers/specs/2026-03-16-x-design.md", rels)
+            out = buf.getvalue()
+            self.assertIn("plan_status.answers.json", out)
+
+    def test_prepare_reports_when_no_candidates(self):
+        with tempfile.TemporaryDirectory() as d, tempfile.TemporaryDirectory() as cache:
+            root = Path(d)
+            (root / "docs/superpowers/plans").mkdir(parents=True)
+            (root / "docs/superpowers/plans/2026-01-01-done.md").write_text(
+                "# Done\n- Create: `src/a.py`\n")
+            (root / "src").mkdir()
+            (root / "src/a.py").write_text("x")
+            with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                            return_value=None), \
+                 mock.patch("commands.plan_status.Path.cwd", return_value=root), \
+                 mock.patch("commands.plan_status.cache_dir", return_value=Path(cache)):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = plan_status.run(["--llm"])
+            self.assertEqual(rc, 0)
+            self.assertIn("no docs need an llm verdict", buf.getvalue().lower())
+
+
+if __name__ == "__main__":
+    unittest.main()