@stylusnexus/work-plan 2026.7.13 → 2026.7.16

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

@@ -59,7 +59,8 @@ class ExportRunJsonTest(unittest.TestCase):
         with patch("commands.export.load_config", return_value={}), \
              patch("commands.export.discover_tracks", return_value=tracks), \
              patch("commands.export.fetch_export_issues", return_value=export_map) as mock_fei, \
-             patch("commands.export.repo_visibility", side_effect=lambda r: vis.get(r)), \
+             patch("commands.export.fetch_visibility_concurrent",
+                   side_effect=lambda repos: {r: vis.get(r) for r in repos}), \
              patch("commands.export.datetime") as mock_dt:
             mock_dt.now.return_value.strftime.return_value = "2026-06-07T12:00:00"
             buf = io.StringIO()
@@ -320,14 +321,13 @@ class ExportCommandUntrackedTest(unittest.TestCase):
 
         vis = vis or {_SHARED_REPO: "PUBLIC"}
 
-        def _fake_open_issues(repo, limit=1000):
-            return open_rows_by_repo.get(repo, [])
-
         with patch("commands.export.load_config", return_value={}), \
              patch("commands.export.discover_tracks", return_value=tracks), \
              patch("commands.export.fetch_export_issues", return_value=export_map), \
-             patch("commands.export.fetch_open_issues", side_effect=_fake_open_issues), \
-             patch("commands.export.repo_visibility", side_effect=lambda r: vis.get(r)), \
+             patch("commands.export.fetch_open_issues_concurrent",
+                   side_effect=lambda repos: {r: open_rows_by_repo.get(r, []) for r in repos}), \
+             patch("commands.export.fetch_visibility_concurrent",
+                   side_effect=lambda repos: {r: vis.get(r) for r in repos}), \
              patch("commands.export.datetime") as mock_dt:
             mock_dt.now.return_value.strftime.return_value = "2026-06-07T12:00:00"
             buf = io.StringIO()
@@ -407,6 +407,25 @@ class ExportCommandUntrackedTest(unittest.TestCase):
         rc, out = self._run_with_mocks(tracks, export_map, open_rows)
         json.dumps(out)  # must not raise
 
+    def test_untracked_order_is_deterministic_across_many_repos(self):
+        """`tracked_repos` must be a first-seen-order list, not a set — a set's
+        iteration order varies run-to-run (hash randomization), which would
+        make `out["untracked"]`'s ordering nondeterministic since it iterates
+        that structure directly to build output (no sort downstream)."""
+        repo_names = [f"org/repo{i}" for i in range(8)]
+        tracks = [_track(f"t{i}", repo_names[i], [i]) for i in range(8)]
+        export_map = {(repo_names[i], i): {"number": i, "title": f"issue{i}",
+                                            "state": "OPEN", "assignees": [], "milestone": None}
+                      for i in range(8)}
+        open_rows = {r: [{"number": 900 + idx, "title": "extra", "state": "OPEN",
+                          "assignees": [], "milestone": None}]
+                     for idx, r in enumerate(repo_names)}
+        vis = {r: "PUBLIC" for r in repo_names}
+        rc, out = self._run_with_mocks(tracks, export_map, open_rows, vis=vis)
+        self.assertEqual(rc, 0)
+        seen_order = [entry["repo"] for entry in out["untracked"]]
+        self.assertEqual(seen_order, repo_names)
+
 
 class ExportCommandGateTest(unittest.TestCase):
     def test_requires_json_flag(self):
@@ -543,6 +562,139 @@ class ExportPlanBadgeTest(unittest.TestCase):
         self.assertEqual(badge, {"rel": "docs/plans/p.md", "resolved": False})
 
 
+class ExportPlanBadgeBatchingTest(unittest.TestCase):
+    """#422: linked plans sharing a local clone batch their git history into
+    ONE paths_last_commit_dates call instead of one per doc/declared path."""
+
+    def _write_plan(self, root, rel, body):
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body)
+
+    def _track(self, name, folder, plan_rel):
+        return SimpleNamespace(
+            name=name, repo="o/r", tier="private", folder=folder,
+            path=Path(f"/tmp/notes/{name}.md"), has_frontmatter=True,
+            meta={"status": "active", "plan": plan_rel, "github": {"repo": "o/r", "issues": []}})
+
+    def _run(self, tracks, local_by_folder, paths_side_effect=None):
+        import io
+        import tempfile as _tf
+        from contextlib import redirect_stdout
+        from datetime import date as _date
+
+        def _resolve_local(folder, cfg):
+            return local_by_folder.get(folder)
+
+        with patch("commands.export.load_config", return_value={}), \
+             patch("commands.export.discover_tracks", return_value=tracks), \
+             patch("commands.export.fetch_export_issues", return_value={}), \
+             patch("commands.export.fetch_visibility_concurrent", return_value={}), \
+             patch("commands.export.fetch_open_issues_concurrent", return_value={}), \
+             patch("commands.export.resolve_local_path_for_folder", side_effect=_resolve_local), \
+             patch("commands.export.paths_last_commit_dates",
+                   side_effect=paths_side_effect or (lambda paths, root: {})) as mock_pld, \
+             patch("commands.export.datetime") as mock_dt:
+            mock_dt.now.return_value.strftime.return_value = "2026-06-07T12:00:00"
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = export_cmd.run(["--json"])
+            return rc, json.loads(buf.getvalue()), mock_pld
+
+    def test_two_tracks_same_clone_share_one_batched_call(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            self._write_plan(root, "docs/plans/a.md",
+                             "# A\n**Files:**\n- Create: `src/a.ts`\n")
+            self._write_plan(root, "docs/plans/b.md",
+                             "# B\n**Files:**\n- Create: `src/b.ts`\n")
+            (root / "src").mkdir()
+            (root / "src/a.ts").write_text("a")
+            (root / "src/b.ts").write_text("b")
+            track_a = self._track("alpha", "demo", "docs/plans/a.md")
+            track_b = self._track("beta", "demo", "docs/plans/b.md")
+
+            rc, out, mock_pld = self._run([track_a, track_b], {"demo": root})
+
+            self.assertEqual(rc, 0)
+            self.assertEqual(mock_pld.call_count, 1)
+            called_paths, called_root = mock_pld.call_args[0]
+            self.assertEqual(called_root, root)
+            self.assertEqual(
+                set(called_paths),
+                {"docs/plans/a.md", "docs/plans/b.md", "src/a.ts", "src/b.ts"},
+            )
+
+    def test_two_tracks_different_clones_batch_independently(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d1, tempfile.TemporaryDirectory() as d2:
+            root1, root2 = Path(d1), Path(d2)
+            self._write_plan(root1, "docs/plans/a.md", "# A\n")
+            self._write_plan(root2, "docs/plans/b.md", "# B\n")
+            track_a = self._track("alpha", "repo1", "docs/plans/a.md")
+            track_b = self._track("beta", "repo2", "docs/plans/b.md")
+
+            rc, out, mock_pld = self._run(
+                [track_a, track_b], {"repo1": root1, "repo2": root2})
+
+            self.assertEqual(rc, 0)
+            self.assertEqual(mock_pld.call_count, 2)
+            roots_called = {c.args[1] for c in mock_pld.call_args_list}
+            self.assertEqual(roots_called, {root1, root2})
+
+    def test_unresolved_tracks_never_trigger_a_batch_call(self):
+        track = self._track("alpha", "missing", "docs/plans/a.md")
+        rc, out, mock_pld = self._run([track], {})  # no local clone resolves
+        self.assertEqual(rc, 0)
+        mock_pld.assert_not_called()
+
+    def test_overlapping_declared_path_across_two_plans_deduped_in_one_call(self):
+        """Two linked plans in the same clone that both declare the SAME
+        path — the shared path appears once in the batched request."""
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            self._write_plan(root, "docs/plans/a.md",
+                             "# A\n**Files:**\n- Create: `src/shared.ts`\n")
+            self._write_plan(root, "docs/plans/b.md",
+                             "# B\n**Files:**\n- Modify: `src/shared.ts`\n")
+            (root / "src").mkdir()
+            (root / "src/shared.ts").write_text("shared")
+            track_a = self._track("alpha", "demo", "docs/plans/a.md")
+            track_b = self._track("beta", "demo", "docs/plans/b.md")
+
+            rc, out, mock_pld = self._run([track_a, track_b], {"demo": root})
+
+            self.assertEqual(mock_pld.call_count, 1)
+            called_paths = mock_pld.call_args[0][0]
+            self.assertEqual(called_paths.count("src/shared.ts"), 1)
+
+    def test_batched_run_produces_correct_verdict_and_lie_gap(self):
+        """Same body/expected verdict as ExportPlanBadgeTest's direct-call
+        test_resolved_badge_with_lie_gap — batching changes call count, not
+        verdict/lie_gap semantics."""
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            body = ("# P\n\n**Files:**\n- Create: `src/new.ts`\n"
+                    "- [ ] Step 1\n- [ ] Step 2\n")
+            self._write_plan(root, "docs/plans/p.md", body)
+            (root / "src").mkdir()
+            (root / "src/new.ts").write_text("export const x = 1")
+            track = self._track("alpha", "demo", "docs/plans/p.md")
+
+            rc, out, mock_pld = self._run([track], {"demo": root})
+
+        self.assertEqual(rc, 0)
+        badge = out["tracks"][0]["plan"]
+        self.assertTrue(badge["resolved"])
+        self.assertEqual(badge["verdict"], "shipped")
+        self.assertEqual(badge["files_present"], 1)
+        self.assertEqual(badge["files_declared"], 1)
+        self.assertTrue(badge["lie_gap"])
+
+
 class ExportHotByTrackTest(unittest.TestCase):
     def test_export_marks_in_progress_from_hot_branch(self):
         import io
@@ -556,8 +708,9 @@ class ExportHotByTrackTest(unittest.TestCase):
              patch("commands.export.discover_tracks", return_value=[track]), \
              patch("commands.export.fetch_export_issues",
                    return_value={("o/r", 1): issue}), \
-             patch("commands.export.fetch_open_issues", return_value=[]), \
-             patch("commands.export.repo_visibility", return_value="PRIVATE"), \
+             patch("commands.export.fetch_open_issues_concurrent", return_value={}), \
+             patch("commands.export.fetch_visibility_concurrent",
+                   side_effect=lambda repos: {r: "PRIVATE" for r in repos}), \
              patch("commands.export.resolve_local_path_for_folder",
                    return_value=Path("/repo")), \
              patch("commands.export.hot_issue_numbers", return_value={1}), \

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

@@ -12,7 +12,9 @@ from lib.github_state import (
     fetch_issues, fetch_issue, fetch_issues_concurrent,
     fetch_repo_issues_graphql, fetch_export_issues, _normalize_gql_node,
     extract_priority, fetch_recent_issues, short_milestone,
-    repo_visibility, _VIS_CACHE, fetch_open_issues,
+    repo_visibility, _VIS_CACHE, fetch_open_issues, repo_full_name,
+    fetch_visibility_concurrent, fetch_open_issues_concurrent,
+    gh_auth_status,
     _GQL_FIELDS_LEAN, _GQL_FIELDS_FULL,
     _gql_query, _GQL_ISSUE_DEPS,
 )
@@ -104,6 +106,56 @@ class RepoVisibilityTest(unittest.TestCase):
         self.assertEqual(m.call_count, 1)
 
 
+class FetchVisibilityConcurrentTest(unittest.TestCase):
+    """Unit tests for the per-repo concurrent batch fetch_visibility_concurrent() (#424)."""
+
+    @patch("lib.github_state.repo_visibility")
+    def test_returns_keyed_dict_per_repo(self, mock_rv):
+        mock_rv.side_effect = lambda r: {"org/a": "PUBLIC", "org/b": "PRIVATE"}.get(r)
+        result = fetch_visibility_concurrent(["org/a", "org/b"])
+        self.assertEqual(result, {"org/a": "PUBLIC", "org/b": "PRIVATE"})
+
+    @patch("lib.github_state.repo_visibility")
+    def test_dedupes_repeated_repos(self, mock_rv):
+        mock_rv.return_value = "PUBLIC"
+        fetch_visibility_concurrent(["org/a", "org/a", "org/a"])
+        self.assertEqual(mock_rv.call_count, 1)
+
+    @patch("lib.github_state.repo_visibility")
+    def test_falsy_repos_filtered(self, mock_rv):
+        mock_rv.return_value = "PUBLIC"
+        result = fetch_visibility_concurrent(["org/a", None, "", "org/a"])
+        self.assertEqual(list(result.keys()), ["org/a"])
+
+    def test_empty_input_returns_empty_dict_no_gh_call(self):
+        with patch("lib.github_state.repo_visibility") as mock_rv:
+            self.assertEqual(fetch_visibility_concurrent([]), {})
+            mock_rv.assert_not_called()
+
+    @patch("lib.github_state.repo_visibility")
+    def test_concurrency_bound_is_respected(self, mock_rv):
+        """Peak simultaneous in-flight calls never exceeds max_workers, and
+        does exceed 1 — proving work is genuinely bounded-concurrent, not
+        serial (#424 acceptance criteria)."""
+        import threading, time
+        lock = threading.Lock()
+        state = {"current": 0, "peak": 0}
+
+        def _tracked(repo):
+            with lock:
+                state["current"] += 1
+                state["peak"] = max(state["peak"], state["current"])
+            time.sleep(0.05)
+            with lock:
+                state["current"] -= 1
+            return "PUBLIC"
+        mock_rv.side_effect = _tracked
+        repos = [f"org/repo{i}" for i in range(10)]
+        fetch_visibility_concurrent(repos, max_workers=3)
+        self.assertLessEqual(state["peak"], 3)
+        self.assertGreater(state["peak"], 1)
+
+
 _ISSUE_JSON = '{"number": 1, "state": "OPEN", "labels": [], "title": "t", "milestone": null, "url": "u", "closedAt": null, "body": "", "updatedAt": "2026-01-01T00:00:00Z", "assignees": []}'
 _ISSUE_DICT = {"number": 1, "state": "OPEN", "labels": [], "title": "t", "milestone": None, "url": "u", "closedAt": None, "body": "", "updatedAt": "2026-01-01T00:00:00Z", "assignees": []}
 
@@ -544,6 +596,57 @@ class FetchOpenIssuesTest(unittest.TestCase):
         self.assertIsInstance(result, list)
 
 
+class FetchOpenIssuesConcurrentTest(unittest.TestCase):
+    """Unit tests for the per-repo concurrent batch fetch_open_issues_concurrent() (#424)."""
+
+    @patch("lib.github_state.fetch_open_issues")
+    def test_returns_keyed_dict_per_repo(self, mock_foi):
+        mock_foi.side_effect = lambda repo: [{"number": 1, "repo": repo}]
+        result = fetch_open_issues_concurrent(["org/a", "org/b"])
+        self.assertEqual(result["org/a"], [{"number": 1, "repo": "org/a"}])
+        self.assertEqual(result["org/b"], [{"number": 1, "repo": "org/b"}])
+
+    @patch("lib.github_state.fetch_open_issues")
+    def test_dedupes_repeated_repos(self, mock_foi):
+        mock_foi.return_value = []
+        fetch_open_issues_concurrent(["org/a", "org/a", "org/a"])
+        self.assertEqual(mock_foi.call_count, 1)
+
+    @patch("lib.github_state.fetch_open_issues")
+    def test_falsy_repos_filtered(self, mock_foi):
+        mock_foi.return_value = []
+        result = fetch_open_issues_concurrent(["org/a", None, "", "org/a"])
+        self.assertEqual(list(result.keys()), ["org/a"])
+
+    def test_empty_input_returns_empty_dict_no_gh_call(self):
+        with patch("lib.github_state.fetch_open_issues") as mock_foi:
+            self.assertEqual(fetch_open_issues_concurrent([]), {})
+            mock_foi.assert_not_called()
+
+    @patch("lib.github_state.fetch_open_issues")
+    def test_concurrency_bound_is_respected(self, mock_foi):
+        """Peak simultaneous in-flight calls never exceeds max_workers, and
+        does exceed 1 — proving work is genuinely bounded-concurrent, not
+        serial (#424 acceptance criteria)."""
+        import threading, time
+        lock = threading.Lock()
+        state = {"current": 0, "peak": 0}
+
+        def _tracked(repo):
+            with lock:
+                state["current"] += 1
+                state["peak"] = max(state["peak"], state["current"])
+            time.sleep(0.05)
+            with lock:
+                state["current"] -= 1
+            return []
+        mock_foi.side_effect = _tracked
+        repos = [f"org/repo{i}" for i in range(10)]
+        fetch_open_issues_concurrent(repos, max_workers=3)
+        self.assertLessEqual(state["peak"], 3)
+        self.assertGreater(state["peak"], 1)
+
+
 class GqlFieldSetsTest(unittest.TestCase):
     def test_lean_set_requests_labels(self):
         # The export path uses the lean set; without labels the in-progress
@@ -608,5 +711,44 @@ class NormalizeDepsTest(unittest.TestCase):
         self.assertFalse(out["deps_truncated"])
 
 
+class TestRepoFullName(unittest.TestCase):
+    def test_returns_full_name_on_success(self):
+        fake = MagicMock(returncode=0, stdout="org/repo-renamed\n", stderr="")
+        with patch("lib.github_state.subprocess.run", return_value=fake) as m:
+            result = repo_full_name("org/repo-old")
+        self.assertEqual(result, "org/repo-renamed")
+        args = m.call_args[0][0]
+        self.assertEqual(args, ["gh", "api", "repos/org/repo-old", "--jq", ".full_name"])
+
+    def test_none_on_nonzero_exit(self):
+        fake = MagicMock(returncode=1, stdout="", stderr="not found")
+        with patch("lib.github_state.subprocess.run", return_value=fake):
+            self.assertIsNone(repo_full_name("org/gone"))
+
+    def test_none_on_invalid_slug(self):
+        self.assertIsNone(repo_full_name("not-a-slug"))
+
+    def test_none_on_subprocess_exception(self):
+        with patch("lib.github_state.subprocess.run", side_effect=OSError("boom")):
+            self.assertIsNone(repo_full_name("org/repo"))
+
+
+def _gh_authenticated():
+    return gh_auth_status()["authenticated"]
+
+
+class TestRepoFullNameLiveRedirect(unittest.TestCase):
+    def test_musical_family_trees_redirect_is_still_live(self):
+        # The actual repo this whole design's incident was about. If this ever
+        # stops returning the renamed slug, the redirect has lapsed and the
+        # design's core "gh api repos/<slug> follows GitHub's own rename
+        # redirect" assumption needs re-verifying before trusting doctor's
+        # output on real data.
+        if not _gh_authenticated():
+            self.skipTest("gh not authenticated — skipping live network check")
+        result = repo_full_name("evemcgivern/musical-family-trees")
+        self.assertEqual(result, "evemcgivern/soundstellation")
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -188,6 +188,36 @@ class RemoteAndOwnershipTest(unittest.TestCase):
                 self.assertTrue(notes_vcs.is_owned(Path(d)))
 
 
+class DirtyPathsCheckedTest(unittest.TestCase):
+    def test_ok_true_on_clean_tree(self):
+        with tempfile.TemporaryDirectory() as d:
+            with patch.object(notes_vcs, "_git", _FakeGit(porcelain="")):
+                ok, paths = notes_vcs.dirty_paths_checked(Path(d))
+        self.assertTrue(ok)
+        self.assertEqual(paths, set())
+
+    def test_ok_true_with_dirty_paths(self):
+        with tempfile.TemporaryDirectory() as d:
+            with patch.object(notes_vcs, "_git",
+                                _FakeGit(porcelain=" M foo.md\n?? bar.md\n")):
+                ok, paths = notes_vcs.dirty_paths_checked(Path(d))
+        self.assertTrue(ok)
+        self.assertEqual(paths, {"foo.md", "bar.md"})
+
+    def test_ok_false_on_git_call_failure(self):
+        with tempfile.TemporaryDirectory() as d:
+            with patch.object(notes_vcs, "_git", _FakeGit(missing=True)):
+                ok, paths = notes_vcs.dirty_paths_checked(Path(d))
+        self.assertFalse(ok)
+        self.assertEqual(paths, set())
+
+    def test_dirty_paths_thin_wrapper_matches_checked(self):
+        with tempfile.TemporaryDirectory() as d:
+            with patch.object(notes_vcs, "_git",
+                                _FakeGit(porcelain=" M foo.md\n")):
+                self.assertEqual(notes_vcs.dirty_paths(Path(d)), {"foo.md"})
+
+
 class DirtyPathsTest(unittest.TestCase):
     def test_parses_porcelain_into_path_set(self):
         body = " M alpha.md\n?? beta.md\n D gone.md\n"

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

@@ -9,7 +9,7 @@ from unittest.mock import patch
 SKILL_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(SKILL_ROOT))
 
-from lib.tracks import discover_tracks, discover_archived_tracks
+from lib.tracks import discover_tracks, discover_archived_tracks, iter_private_track_paths
 
 FIXTURES = Path(__file__).parent / "fixtures" / "notes_root"
 
@@ -463,5 +463,42 @@ class DiscoverArchivedSharedTest(unittest.TestCase):
             self.assertNotIn("WARN:", stderr_buf.getvalue())
 
 
+class TestIterPrivateTrackPaths(unittest.TestCase):
+    def _make_tree(self, root: Path):
+        (root / "proj-a").mkdir(parents=True)
+        (root / "proj-a" / "track-one.md").write_text("---\n---\nbody")
+        (root / "proj-a" / "_draft.md").write_text("---\n---\nbody")
+        (root / "proj-a" / "archive").mkdir()
+        (root / "proj-a" / "archive" / "old-track.md").write_text("---\n---\nbody")
+        (root / "proj-a" / ".hidden.md").write_text("---\n---\nbody")
+
+    def test_excludes_archive_by_default(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._make_tree(root)
+            paths = iter_private_track_paths(root, include_archive=False)
+            names = {p.name for p in paths}
+            self.assertEqual(names, {"track-one.md"})
+
+    def test_includes_archive_when_requested(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._make_tree(root)
+            paths = iter_private_track_paths(root, include_archive=True)
+            names = {p.name for p in paths}
+            self.assertEqual(names, {"track-one.md", "old-track.md"})
+
+    def test_skips_dotfile_underscore_dash_prefixed_names_in_both_modes(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._make_tree(root)
+            (root / "proj-a" / "-dash.md").write_text("---\n---\nbody")
+            for include_archive in (False, True):
+                names = {p.name for p in iter_private_track_paths(root, include_archive)}
+                self.assertNotIn("_draft.md", names)
+                self.assertNotIn(".hidden.md", names)
+                self.assertNotIn("-dash.md", names)
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/work_plan.py

@@ -61,6 +61,7 @@ SUBCOMMANDS = {
     "in-progress": "commands.in_progress",
     "export": "commands.export",
     "which-repo": "commands.which_repo",
+    "doctor": "commands.doctor",
     "auth-status": "commands.auth_status",
     "list-open-issues": "commands.list_open_issues",
     "set": "commands.set_field",
@@ -259,6 +260,17 @@ DESCRIPTIONS = [
      "Resolve the current directory to one configured repo — by local clone path first, then the git `origin` remote. Prints the matched config key + GitHub slug, or reports no match. Read-only. Underlies `brief` cwd auto-scope and the VS Code viewer's repo auto-focus.",
      "Rarely run by hand — it's the shared resolver the viewer and `brief` call. Useful to confirm which repo a checkout maps to.",
      "/work-plan which-repo --json"),
+    ("doctor", "[--json] [--fix]",
+     "Detect drift between config.yml, local git clones, GitHub, and notes_root track "
+     "frontmatter — a renamed local folder or GitHub repo that config.yml no longer "
+     "matches, a non-git local path, duplicate entries, an invalid/missing notes_root, "
+     "an orphaned notes folder, or a stale per-track github.repo. --fix corrects only "
+     "the two mechanically-safe cases (a GitHub-confirmed rename, a stale track slug) "
+     "and always re-scans afterward before deciding success.",
+     "Run right after renaming a project's local folder or its GitHub repo — this is "
+     "exactly the class of bug that silently breaks the VS Code viewer's Auto Focus "
+     "Repo setting with zero visible signal.",
+     "/work-plan doctor --fix"),
 ]
 
 
@@ -352,6 +364,14 @@ _READONLY_SUBCOMMANDS = frozenset({
     # plan-branch manages its OWN commits on the plan branch (init seeds +
     # commits the skeleton itself); the auto-commit hooks must not also fire.
     "plan-branch",
+    # doctor writes config.yml (unversioned, outside any repo) and private
+    # notes_root/ frontmatter under --fix, but never a repo's shared
+    # .work-plan/ tier — so it's read-only from the dispatcher's perspective
+    # too, sidestepping _shared_precommit_state's plan_worktree.ensure_worktree
+    # side effect. doctor --fix manages its own notes-vcs commit directly
+    # (see commands/doctor.py's dirty-file policy), same self-managed-commit
+    # precedent as plan-branch.
+    "doctor",
 })