@stylusnexus/work-plan 2026.6.9

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

@@ -0,0 +1,51 @@
+"""Pure verdict classification over gathered evidence. No I/O — fully unit-testable.
+
+Thresholds are module constants so a later phase can make them configurable
+without touching call sites.
+"""
+from dataclasses import dataclass
+from datetime import date
+from typing import Optional
+
+SHIPPED_PCT = 80.0      # >= this % of declared files satisfied -> shipped
+PARTIAL_PCT = 20.0      # >= this % -> partial
+BOXES_STALE_PCT = 50.0  # checked-box % below this on a shipped plan -> "boxes stale"
+DEAD_DAYS = 60          # 0 files satisfied AND untouched beyond this -> dead
+FOREIGN_RATIO = 0.7     # >= this fraction of declared paths outside repo -> foreign
+
+
+@dataclass
+class Verdict:
+    label: str      # shipped | partial | dead | foreign | manifest-less
+    glyph: str
+    rationale: str
+
+
+def classify(
+    score,
+    checkbox_done: int,
+    checkbox_total: int,
+    last_touched: Optional[date],
+    today: date,
+    dead_days: int = DEAD_DAYS,
+) -> Verdict:
+    if score.total == 0:
+        return Verdict("manifest-less", "\U0001f47b",
+                       "no file-manifest — needs LLM verdict (Phase 1b)")
+
+    pct = score.pct
+    files = f"{score.satisfied}/{score.total} declared files present"
+
+    if pct >= SHIPPED_PCT:
+        chk_pct = (checkbox_done / checkbox_total * 100.0) if checkbox_total else 0.0
+        stale = " (boxes stale)" if chk_pct < BOXES_STALE_PCT else ""
+        return Verdict("shipped", "✅", f"{files}{stale}")
+
+    if pct >= PARTIAL_PCT:
+        return Verdict("partial", "\U0001f7e1", files)
+
+    if last_touched is not None and (today - last_touched).days > dead_days:
+        age = (today - last_touched).days
+        return Verdict("dead", "\U0001f480", f"{files}, untouched {age}d")
+
+    return Verdict("partial", "\U0001f7e1", f"{files} (early)")

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

@@ -0,0 +1,39 @@
+"""Confirm-token gate so non-interactive callers (the VS Code extension) can
+surface the public-repo heads-up as their own dialog instead of a TTY prompt.
+
+needs_confirm() fails CLOSED: PUBLIC or unknown visibility both require confirm.
+Unknown visibility can be opted out of via cfg["assume_private_when_unknown"]=True
+(for all-private teams that want to avoid the prompt on transient gh failures).
+PUBLIC is never suppressed by this flag — the leak guarantee is unconditional.
+
+The token is a deterministic hash of (repo, track) — no randomness (3.9 stdlib,
+and stable so the re-invocation matches). It is not a security boundary; it just
+proves the caller saw the heads-up for THIS write."""
+import hashlib
+from lib.github_state import repo_visibility
+
+
+def needs_confirm(repo: str, cfg: dict = None) -> bool:
+    """True when a write to `repo` needs the public-repo confirm heads-up.
+
+    PUBLIC  → always True (never suppressed — the leak guarantee).
+    PRIVATE → False.
+    Unknown visibility (gh couldn't say / offline) → True (fail CLOSED) UNLESS
+    cfg opts out via `assume_private_when_unknown: true`, which lets an
+    all-private team avoid the prompt on transient gh-lookup failures. PUBLIC is
+    never affected by this flag."""
+    vis = repo_visibility(repo)
+    if vis == "PUBLIC":
+        return True
+    if vis == "PRIVATE":
+        return False
+    # vis is None → unknown / offline. Fail closed unless explicitly opted out.
+    if cfg and cfg.get("assume_private_when_unknown"):
+        return False
+    return True
+
+def make_token(repo: str, track: str) -> str:
+    return hashlib.sha256(f"{repo}::{track}".encode("utf-8")).hexdigest()[:16]
+
+def valid_token(token: str, repo: str, track: str) -> bool:
+    return bool(token) and token == make_token(repo, track)

package/skills/work-plan/tests/fixtures/notes_root/critforge/archive/shipped/old.md

@@ -0,0 +1,10 @@
+---
+track: old
+status: shipped
+launch_priority: P2
+github:
+  repo: stylusnexus/CritForge
+  issues: [50]
+---
+
+# Old shipped track

package/skills/work-plan/tests/fixtures/notes_root/critforge/example.md

@@ -0,0 +1,11 @@
+---
+track: example
+status: active
+launch_priority: P1
+github:
+  repo: stylusnexus/CritForge
+  issues: [100, 200]
+next_up: [100]
+---
+
+# Example

package/skills/work-plan/tests/fixtures/notes_root/critforge/no_frontmatter.md

@@ -0,0 +1 @@
+# No frontmatter

package/skills/work-plan/tests/fixtures/notes_root/loose_at_root.md

@@ -0,0 +1 @@
+# Loose

package/skills/work-plan/tests/fixtures/track_with_frontmatter.md

@@ -0,0 +1,14 @@
+---
+track: tabletop
+status: active
+launch_priority: P1
+github:
+  repo: stylusnexus/CritForge
+  issues: [4254, 4127]
+  branches: []
+next_up: [4254]
+---
+
+# Tabletop
+
+Body content.

package/skills/work-plan/tests/fixtures/track_without_frontmatter.md

@@ -0,0 +1,3 @@
+# Some plan
+
+Body only.

package/skills/work-plan/tests/fixtures/with_status_table.md

@@ -0,0 +1,9 @@
+# Track
+
+## Issues
+
+| # | Title | Status |
+|---|---|---|
+| #4254 | admin polls | 🔲 Open |
+| #4127 | dice roller | ✅ Shipped |
+| #925 | wild magic | 🟡 In PR (#4137) |

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

@@ -0,0 +1,273 @@
+"""Tests for the non-interactive close command (issue #87, Phase 3a).
+
+Covers:
+- close <track> --state=parked on a PRIVATE repo → status set to parked,
+  write_file called, shutil.move NOT called (stays in place), rc 0.
+- --state=shipped on a private repo → status shipped, write_file called,
+  shutil.move called to archive/shipped/, rc 0.
+- --state=abandoned → moves to archive/abandoned/.
+- Missing --state → rc 2, no write.
+- Invalid --state=bogus → rc 2, no write.
+- --note="wrapped up" → the body passed to write_file contains the ## Wrap-up
+  section with the note.
+- Public repo, no token → prints needs_confirm JSON, no write/move, rc 0;
+  token equals make_token(repo, track.name).
+- Public repo with valid --confirm=<token> → performs the close (write/move
+  happen), rc 0.
+- No input()/prompt_input is reached on the flagged path (patch them to raise).
+"""
+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 patch
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import close
+from lib.write_guard import make_token
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _track(*, name="alpha", repo="ok/repo", status="active"):
+    return SimpleNamespace(
+        name=name,
+        path=Path(f"/tmp/fake/{name}.md"),
+        body="# fake body",
+        meta={
+            "track": name,
+            "status": status,
+            "github": {"repo": repo},
+        },
+        has_frontmatter=True,
+        repo=repo,
+    )
+
+
+def _drive(args, track=None, vis="PRIVATE"):
+    """Run close.run(args) with all external I/O mocked.
+
+    vis controls what repo_visibility returns (used by needs_confirm).
+    track defaults to a single private-repo track named 'alpha'.
+    """
+    if track is None:
+        track = _track()
+    # notes_root must be a parent of the track path so relative_to() works
+    cfg = {"notes_root": "/tmp/fake", "repos": {"ok": {"github": "ok/repo"}}}
+
+    with patch("commands.close.load_config", return_value=cfg), \
+         patch("commands.close.discover_tracks", return_value=[track]), \
+         patch("commands.close.find_track_by_name", return_value=track), \
+         patch("lib.write_guard.repo_visibility", return_value=vis), \
+         patch("commands.close.write_file") as mw, \
+         patch("commands.close.shutil") as ms, \
+         patch("pathlib.Path.mkdir"):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = close.run(args)
+    return rc, mw, ms, buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+class CloseNonInteractiveTest(unittest.TestCase):
+
+    # ------------------------------------------------------------------
+    # State: parked (stays in place)
+    # ------------------------------------------------------------------
+
+    def test_parked_private_write_no_move(self):
+        """close <track> --state=parked on PRIVATE repo → write_file called,
+        shutil.move NOT called, rc 0."""
+        rc, mw, ms, out = _drive(["alpha", "--state=parked"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        # status updated to parked
+        written_meta = mw.call_args[0][1]
+        self.assertEqual(written_meta["status"], "parked")
+        # move must NOT be called for parked
+        ms.move.assert_not_called()
+        self.assertIn("parked", out)
+
+    # ------------------------------------------------------------------
+    # State: shipped (moves to archive/shipped/)
+    # ------------------------------------------------------------------
+
+    def test_shipped_private_write_and_move(self):
+        """--state=shipped on private repo → write_file called, shutil.move
+        called to archive/shipped/, rc 0."""
+        rc, mw, ms, out = _drive(["alpha", "--state=shipped"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written_meta = mw.call_args[0][1]
+        self.assertEqual(written_meta["status"], "shipped")
+        ms.move.assert_called_once()
+        # Destination path should contain archive/shipped
+        dest_arg = ms.move.call_args[0][1]
+        self.assertIn("archive", dest_arg)
+        self.assertIn("shipped", dest_arg)
+
+    # ------------------------------------------------------------------
+    # State: abandoned (moves to archive/abandoned/)
+    # ------------------------------------------------------------------
+
+    def test_abandoned_private_write_and_move(self):
+        """--state=abandoned → moves to archive/abandoned/."""
+        rc, mw, ms, out = _drive(["alpha", "--state=abandoned"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written_meta = mw.call_args[0][1]
+        self.assertEqual(written_meta["status"], "abandoned")
+        ms.move.assert_called_once()
+        dest_arg = ms.move.call_args[0][1]
+        self.assertIn("archive", dest_arg)
+        self.assertIn("abandoned", dest_arg)
+
+    # ------------------------------------------------------------------
+    # Missing / invalid --state
+    # ------------------------------------------------------------------
+
+    def test_missing_state_returns_rc2(self):
+        """Missing --state → rc 2, no write."""
+        rc, mw, ms, out = _drive(["alpha"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+        ms.move.assert_not_called()
+
+    def test_invalid_state_returns_rc2(self):
+        """Invalid --state=bogus → rc 2, no write."""
+        rc, mw, ms, out = _drive(["alpha", "--state=bogus"])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+        ms.move.assert_not_called()
+
+    def test_missing_track_name_returns_rc2(self):
+        """No positional args at all → rc 2 (usage error)."""
+        rc, mw, ms, out = _drive([])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+    # ------------------------------------------------------------------
+    # --note flag
+    # ------------------------------------------------------------------
+
+    def test_note_appended_to_body(self):
+        """--note='wrapped up' → body passed to write_file contains
+        ## Wrap-up section with the note."""
+        rc, mw, ms, out = _drive(["alpha", "--state=parked", "--note=wrapped up"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written_body = mw.call_args[0][2]
+        self.assertIn("## Wrap-up", written_body)
+        self.assertIn("wrapped up", written_body)
+
+    def test_no_note_no_wrap_up_section(self):
+        """No --note flag → body does NOT contain ## Wrap-up section."""
+        rc, mw, ms, out = _drive(["alpha", "--state=parked"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written_body = mw.call_args[0][2]
+        self.assertNotIn("## Wrap-up", written_body)
+
+    # ------------------------------------------------------------------
+    # Confirm-token gate (public repo)
+    # ------------------------------------------------------------------
+
+    def test_public_repo_no_token_returns_needs_confirm_json(self):
+        """Public repo, no token → prints needs_confirm JSON, no write/move,
+        rc 0; token equals make_token(repo, track.name)."""
+        track = _track(name="alpha", repo="ok/repo")
+        rc, mw, ms, out = _drive(["alpha", "--state=shipped"], track=track, vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        ms.move.assert_not_called()
+        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(self):
+        """Unknown visibility (None) → also requires confirm."""
+        track = _track(name="alpha", repo="ok/repo")
+        rc, mw, ms, out = _drive(["alpha", "--state=parked"], track=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_close(self):
+        """Public repo with valid --confirm=<token> → performs the close
+        (write_file called), rc 0."""
+        track = _track(name="alpha", repo="ok/repo")
+        tok = make_token("ok/repo", "alpha")
+        rc, mw, ms, out = _drive(
+            ["alpha", "--state=parked", f"--confirm={tok}"],
+            track=track, vis="PUBLIC"
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+
+    def test_public_repo_with_valid_confirm_shipped_moves(self):
+        """Public repo with valid --confirm=<token> + --state=shipped →
+        write_file AND shutil.move both called, rc 0."""
+        track = _track(name="alpha", repo="ok/repo")
+        tok = make_token("ok/repo", "alpha")
+        rc, mw, ms, out = _drive(
+            ["alpha", "--state=shipped", f"--confirm={tok}"],
+            track=track, vis="PUBLIC"
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        ms.move.assert_called_once()
+
+    def test_public_repo_wrong_token_blocks_write(self):
+        """Public repo with wrong confirm token → blocked, no write, rc 0."""
+        track = _track(name="alpha", repo="ok/repo")
+        rc, mw, ms, out = _drive(
+            ["alpha", "--state=shipped", "--confirm=wrongtoken"],
+            track=track, vis="PUBLIC"
+        )
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        data = json.loads(out.strip())
+        self.assertTrue(data["needs_confirm"])
+
+    # ------------------------------------------------------------------
+    # No input() on non-interactive path
+    # ------------------------------------------------------------------
+
+    def test_no_input_called_on_flagged_path(self):
+        """Flagged paths never call input() or prompt_input, even when
+        --state/--note are provided and the repo is private."""
+        track = _track(name="alpha", repo="ok/repo")
+
+        def _raise(*a, **kw):
+            raise AssertionError("input() must not be called on non-interactive path")
+
+        cfg = {"notes_root": "/tmp/fake-notes", "repos": {"ok": {"github": "ok/repo"}}}
+
+        with patch("builtins.input", side_effect=_raise), \
+             patch("lib.prompts.prompt_input", side_effect=_raise):
+            with patch("commands.close.load_config", return_value=cfg), \
+                 patch("commands.close.discover_tracks", return_value=[track]), \
+                 patch("commands.close.find_track_by_name", return_value=track), \
+                 patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+                 patch("commands.close.write_file"), \
+                 patch("commands.close.shutil"), \
+                 patch("pathlib.Path.mkdir"):
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = close.run(["alpha", "--state=parked", "--note=done"])
+        self.assertEqual(rc, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,51 @@
+"""Tests for closure detection."""
+import unittest
+import sys
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.closure import is_closure_ready, ClosureSignals
+
+
+class ClosureReadyTest(unittest.TestCase):
+    def test_all_signals_green(self):
+        signals = ClosureSignals(
+            all_issues_closed=True,
+            all_branches_done=True,
+            next_up_empty=True,
+            cold_14d=True,
+            no_recent_related_issues=True,
+        )
+        ready, reasons = is_closure_ready(signals)
+        self.assertTrue(ready)
+        self.assertEqual(reasons, [])
+
+    def test_open_issue_blocks_closure(self):
+        signals = ClosureSignals(
+            all_issues_closed=False,
+            all_branches_done=True,
+            next_up_empty=True,
+            cold_14d=True,
+            no_recent_related_issues=True,
+        )
+        ready, reasons = is_closure_ready(signals)
+        self.assertFalse(ready)
+        self.assertIn("open issues remain", " ".join(reasons))
+
+    def test_partial_signals_returns_count(self):
+        signals = ClosureSignals(
+            all_issues_closed=True,
+            all_branches_done=True,
+            next_up_empty=False,
+            cold_14d=False,
+            no_recent_related_issues=True,
+        )
+        ready, reasons = is_closure_ready(signals)
+        self.assertFalse(ready)
+        self.assertEqual(len(reasons), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,85 @@
+"""Tests for config loader."""
+import unittest
+import tempfile
+import sys
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.config import (
+    load_config, ConfigError,
+    resolve_github_for_folder, resolve_local_path_for_folder,
+)
+
+
+class LoadConfigTest(unittest.TestCase):
+    def _write(self, d, content):
+        path = Path(d) / "config.yml"
+        path.write_text(content, encoding="utf-8")
+        return path
+
+    def test_load_dict_shape(self):
+        with tempfile.TemporaryDirectory() as d:
+            path = self._write(d, (
+                "notes_root: /tmp/notes\n"
+                "repos:\n"
+                "  critforge:\n"
+                "    github: stylusnexus/CritForge\n"
+                "    local: /Applications/Development/Projects/CritForge\n"
+            ))
+            cfg = load_config(path)
+            self.assertEqual(cfg["notes_root"], "/tmp/notes")
+            self.assertEqual(cfg["repos"]["critforge"]["github"], "stylusnexus/CritForge")
+            self.assertEqual(cfg["repos"]["critforge"]["local"],
+                             "/Applications/Development/Projects/CritForge")
+
+    def test_load_string_shape_normalizes_to_dict(self):
+        # Backward-friendly: bare string is treated as github-only, no local
+        with tempfile.TemporaryDirectory() as d:
+            path = self._write(d, (
+                "notes_root: /tmp/notes\n"
+                "repos:\n"
+                "  critforge: stylusnexus/CritForge\n"
+            ))
+            cfg = load_config(path)
+            self.assertEqual(cfg["repos"]["critforge"]["github"], "stylusnexus/CritForge")
+            self.assertIsNone(cfg["repos"]["critforge"]["local"])
+
+    def test_missing_file_self_seeds(self):
+        # No install hook exists for plugin installs, so a missing config is
+        # seeded on first load rather than raising.
+        with tempfile.TemporaryDirectory() as d:
+            path = Path(d) / "work-plan" / "config.yml"
+            cfg = load_config(path, notes_root=Path(d) / "notes")
+            self.assertTrue(path.is_file())
+            self.assertEqual(cfg["repos"], {})
+            self.assertIn("notes_root", cfg)
+
+    def test_missing_notes_root_raises(self):
+        with tempfile.TemporaryDirectory() as d:
+            path = self._write(d, "repos:\n  foo: bar/baz\n")
+            with self.assertRaises(ConfigError) as ctx:
+                load_config(path)
+            self.assertIn("notes_root", str(ctx.exception))
+
+
+class ResolveTest(unittest.TestCase):
+    def setUp(self):
+        self.cfg = {
+            "repos": {
+                "critforge": {"github": "stylusnexus/CritForge", "local": "/path/to/critforge"},
+            },
+        }
+
+    def test_resolve_github(self):
+        self.assertEqual(resolve_github_for_folder("critforge", self.cfg), "stylusnexus/CritForge")
+        self.assertIsNone(resolve_github_for_folder("unknown", self.cfg))
+
+    def test_resolve_local_path(self):
+        self.assertEqual(resolve_local_path_for_folder("critforge", self.cfg), Path("/path/to/critforge"))
+        self.assertIsNone(resolve_local_path_for_folder("unknown", self.cfg))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,41 @@
+"""Lazy config seeding — plugin installs run no install hook (issue: org-sharing).
+
+The CLI must create a usable config.yml on first run when one is absent, at a
+stable absolute path, idempotently. Offline; uses temp dirs (never the real HOME).
+"""
+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.config import load_config, ensure_config
+
+
+class EnsureConfigTest(unittest.TestCase):
+    def test_load_config_seeds_when_missing(self):
+        with tempfile.TemporaryDirectory() as d:
+            cfg_path = Path(d) / "work-plan" / "config.yml"
+            notes = Path(d) / "notes"
+            cfg = load_config(cfg_path, notes_root=notes)
+            self.assertTrue(cfg_path.is_file(), "config.yml should be seeded")
+            self.assertEqual(cfg["repos"], {})
+            # notes_root is an ABSOLUTE path (no literal ~), and the dir exists.
+            self.assertEqual(cfg["notes_root"], str(notes))
+            self.assertFalse(cfg["notes_root"].startswith("~"))
+            self.assertTrue(notes.is_dir())
+
+    def test_ensure_config_idempotent(self):
+        with tempfile.TemporaryDirectory() as d:
+            cfg_path = Path(d) / "work-plan" / "config.yml"
+            notes = Path(d) / "notes"
+            self.assertTrue(ensure_config(cfg_path, notes_root=notes))
+            before = cfg_path.read_bytes()
+            self.assertFalse(ensure_config(cfg_path, notes_root=notes))
+            self.assertEqual(cfg_path.read_bytes(), before)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,51 @@
+"""Tests for doc discovery + kind classification."""
+import unittest
+import sys
+import tempfile
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib.doc_discovery import classify_kind, discover_docs, Doc
+
+
+class ClassifyKindTest(unittest.TestCase):
+    def test_superpowers_plan(self):
+        self.assertEqual(classify_kind("docs/superpowers/plans/2026-03-16-x.md"), "plan")
+
+    def test_superpowers_spec(self):
+        self.assertEqual(classify_kind("docs/superpowers/specs/2026-03-16-x-design.md"), "spec")
+
+    def test_design_suffix_is_spec(self):
+        self.assertEqual(classify_kind("docs/plans/2026-02-17-foo-design.md"), "spec")
+
+    def test_plain_docs_plan(self):
+        self.assertEqual(classify_kind("docs/plans/2026-02-17-foo.md"), "plan")
+
+    def test_other_is_adhoc(self):
+        self.assertEqual(classify_kind("notes/random.md"), "adhoc")
+
+
+class DiscoverDocsTest(unittest.TestCase):
+    def test_finds_default_globs_and_dedupes(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            (root / "docs/superpowers/plans").mkdir(parents=True)
+            (root / "docs/plans").mkdir(parents=True)
+            (root / "docs/superpowers/plans/2026-03-16-a.md").write_text("x")
+            (root / "docs/plans/2026-02-17-b-design.md").write_text("x")
+            (root / "docs/plans/README.txt").write_text("ignore")  # not .md
+            docs = discover_docs(root)
+            rels = sorted(x.rel for x in docs)
+            self.assertEqual(rels, [
+                "docs/plans/2026-02-17-b-design.md",
+                "docs/superpowers/plans/2026-03-16-a.md",
+            ])
+            kinds = {x.rel: x.kind for x in docs}
+            self.assertEqual(kinds["docs/superpowers/plans/2026-03-16-a.md"], "plan")
+            self.assertEqual(kinds["docs/plans/2026-02-17-b-design.md"], "spec")
+
+
+if __name__ == "__main__":
+    unittest.main()