@stylusnexus/work-plan 2026.6.13 → 2026.6.14

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

@@ -0,0 +1,145 @@
+"""verdict_override (#286): a frontmatter override pins the verdict and silences
+the lie-gap on plan-status. Offline — frontmatter parse shells to real yq."""
+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
+
+# A plan whose ONE declared file exists (→ mechanical "shipped", file score 100%)
+# but whose two phase checkboxes are unticked → the classic lie-gap shape.
+BODY = (
+    "# Idea Mode UI\n\n"
+    "**Files:**\n"
+    "- Create: `src/new.ts`\n"
+    "- [ ] Step 1: do the thing\n"
+    "- [ ] Step 2: do the other thing\n"
+)
+
+
+def _frontmattered(override: str) -> str:
+    return f"---\nverdict_override: {override}\n---\n{BODY}"
+
+
+def _frontmattered_kv(key: str, value: str) -> str:
+    return f"---\n{key}: {value}\n---\n{BODY}"
+
+
+class OverrideTest(unittest.TestCase):
+    def _row(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):
+                rc = plan_status.run(["--json"])
+        self.assertEqual(rc, 0)
+        return json.loads(buf.getvalue())["docs"][0]
+
+    def _repo(self, d, doc_text):
+        root = Path(d)
+        (root / "docs/superpowers/plans").mkdir(parents=True)
+        (root / "docs/superpowers/plans/p.md").write_text(doc_text)
+        (root / "src").mkdir()
+        (root / "src/new.ts").write_text("export const x = 1")  # 1/1 declared present
+        return root
+
+    def test_baseline_lie_gap_without_override(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, BODY))
+            self.assertEqual(row["verdict"], "shipped")
+            self.assertTrue(row["lie_gap"])      # 0/2 boxes -> lie-gap fires
+            self.assertIsNone(row["override"])
+
+    def test_override_shipped_silences_lie_gap(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, _frontmattered("shipped")))
+            self.assertEqual(row["verdict"], "shipped")
+            self.assertEqual(row["override"], "shipped")
+            self.assertFalse(row["lie_gap"])     # human-confirmed -> no longer a lie
+            self.assertIn("human-confirmed", row["rationale"])
+
+    def test_override_pins_verdict_over_mechanical(self):
+        # Declared file MISSING -> mechanical would be partial; override pins dead.
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            (root / "docs/superpowers/plans").mkdir(parents=True)
+            (root / "docs/superpowers/plans/p.md").write_text(_frontmattered("dead"))
+            # no src/new.ts -> 0/1 files
+            row = self._row(root)
+            self.assertEqual(row["verdict"], "dead")
+            self.assertEqual(row["override"], "dead")
+            self.assertEqual(row["glyph"], "💀")
+
+    def test_invalid_override_value_ignored(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, _frontmattered("done")))  # not a valid verdict
+            self.assertIsNone(row["override"])
+            self.assertTrue(row["lie_gap"])      # falls back to mechanical
+
+    def test_acknowledged_frontmatter_emitted(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, f"---\nacknowledged: true\n---\n{BODY}"))
+            self.assertTrue(row["acknowledged"])
+
+    def test_acknowledged_false_without_frontmatter(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, BODY))
+            self.assertFalse(row["acknowledged"])
+
+    def test_baseline_matching_live_verdict_no_drift(self):
+        # File present → live "shipped"; baseline shipped → no drift.
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, _frontmattered_kv("verdict_baseline", "shipped")))
+            self.assertEqual(row["verdict_baseline"], "shipped")
+            self.assertFalse(row["verdict_drift"])
+
+    def test_baseline_diverged_flags_drift(self):
+        # File MISSING → live "partial"; baseline shipped → drift (regressed).
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            (root / "docs/superpowers/plans").mkdir(parents=True)
+            (root / "docs/superpowers/plans/p.md").write_text(
+                f"---\nverdict_baseline: shipped\n---\n{BODY}")  # no src/new.ts
+            row = self._row(root)
+            self.assertEqual(row["verdict"], "partial")
+            self.assertTrue(row["verdict_drift"])
+
+    def test_override_suppresses_drift(self):
+        # baseline partial, but a human override pins shipped → drift suppressed.
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(
+                d, "---\nverdict_baseline: partial\nverdict_override: shipped\n---\n" + BODY))
+            self.assertEqual(row["verdict"], "shipped")
+            self.assertFalse(row["verdict_drift"])
+
+    def test_no_baseline_no_drift(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, BODY))
+            self.assertIsNone(row["verdict_baseline"])
+            self.assertFalse(row["verdict_drift"])
+
+    def test_offtree_paths_flagged(self):
+        # A plan declaring an out-of-tree path surfaces it read-only (#286 slice 3).
+        body = ("# P\n\n**Files:**\n- Create: `src/new.ts`\n"
+                "- Create: `../sibling/escape.ts`\n- [ ] Step 1\n")
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, body))
+            self.assertEqual(row["offtree_paths"], ["../sibling/escape.ts"])
+
+    def test_offtree_paths_empty_for_clean_manifest(self):
+        with tempfile.TemporaryDirectory() as d:
+            row = self._row(self._repo(d, BODY))
+            self.assertEqual(row["offtree_paths"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,131 @@
+"""push-track (#306): promote a private track to the shared tier + push.
+Real temp files for the move; git-worktree helpers + config mocked (offline)."""
+import io
+import json
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout, redirect_stderr
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import push_track
+from lib.frontmatter import parse_file
+from lib.write_guard import make_token
+
+
+class PushTrackTest(unittest.TestCase):
+    def _setup(self, d, tier="private", plan_branch="work-plan/plan"):
+        root = Path(d)
+        notes = root / "notes"; notes.mkdir()
+        priv = notes / "my-feature.md"
+        priv.write_text("---\ntrack: my-feature\n---\n# My Feature\n\nbody\n")
+        shared = root / "repo" / ".work-plan"; shared.mkdir(parents=True)
+        entry = {"github": "o/r", "local": str(root / "repo")}
+        if plan_branch:
+            entry["plan_branch"] = plan_branch
+        cfg = {"notes_root": str(notes), "repos": {"demo": entry}}
+        track = SimpleNamespace(
+            name="my-feature", tier=tier, folder="demo", repo="o/r",
+            path=priv, meta={"track": "my-feature"}, body="# My Feature\n\nbody\n",
+        )
+        return root, cfg, track, shared, priv
+
+    def _drive(self, cfg, track, shared, args, vis="PRIVATE",
+               commit_sha="abc123", push_rc=0):
+        push_proc = SimpleNamespace(returncode=push_rc, stderr="")
+        with mock.patch("commands.push_track.load_config", return_value=cfg), \
+             mock.patch("commands.push_track.discover_tracks", return_value=[track]), \
+             mock.patch("commands.push_track.find_track_by_name", return_value=track), \
+             mock.patch("lib.write_guard.repo_visibility", return_value=vis), \
+             mock.patch("commands.push_track.pw.shared_tier_dir", return_value=shared), \
+             mock.patch("commands.push_track.pw.commit_shared_tier", return_value=commit_sha), \
+             mock.patch("commands.push_track.pw.push_plan_branch", return_value=push_proc) as mpush:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = push_track.run(args)
+        return rc, out.getvalue(), err.getvalue(), mpush
+
+    def test_promotes_and_pushes_private_repo(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature"])
+            self.assertEqual(rc, 0)
+            dest = shared / "my-feature.md"
+            self.assertTrue(dest.is_file())             # written to shared tier
+            self.assertFalse(priv.exists())             # private copy removed
+            meta, _ = parse_file(dest)
+            self.assertEqual(meta["track"], "my-feature")  # frontmatter preserved
+            mpush.assert_called_once()                  # pushed
+
+    def test_no_push_keeps_local(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature", "--no-push"])
+            self.assertEqual(rc, 0)
+            self.assertTrue((shared / "my-feature.md").is_file())
+            mpush.assert_not_called()
+            self.assertIn("plan-branch push", out)
+
+    def test_public_repo_no_token_returns_needs_confirm_no_mutation(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature"], vis="PUBLIC")
+            self.assertEqual(rc, 0)
+            data = json.loads(out)
+            self.assertTrue(data["needs_confirm"])
+            self.assertEqual(data["token"], make_token("o/r", "my-feature"))
+            self.assertFalse((shared / "my-feature.md").exists())  # nothing moved
+            self.assertTrue(priv.exists())                          # private intact
+            mpush.assert_not_called()
+
+    def test_public_repo_with_valid_token_proceeds(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            tok = make_token("o/r", "my-feature")
+            rc, out, err, mpush = self._drive(
+                cfg, track, shared, ["my-feature", f"--confirm={tok}"], vis="PUBLIC")
+            self.assertEqual(rc, 0)
+            self.assertTrue((shared / "my-feature.md").is_file())
+            mpush.assert_called_once()
+
+    def test_public_no_push_skips_gate(self):
+        # --no-push keeps it local, so no exposure gate even on a public repo.
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            rc, out, err, mpush = self._drive(
+                cfg, track, shared, ["my-feature", "--no-push"], vis="PUBLIC")
+            self.assertEqual(rc, 0)
+            self.assertTrue((shared / "my-feature.md").is_file())
+            mpush.assert_not_called()
+
+    def test_already_shared_aborts(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d, tier="shared")
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature"])
+            self.assertEqual(rc, 1)
+            self.assertIn("already in the shared tier", err)
+
+    def test_no_plan_branch_hints_init(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d, plan_branch=None)
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature"])
+            self.assertEqual(rc, 1)
+            self.assertIn("plan-branch init", err)
+
+    def test_dest_exists_aborts(self):
+        with tempfile.TemporaryDirectory() as d:
+            _, cfg, track, shared, priv = self._setup(d)
+            (shared / "my-feature.md").write_text("# already here\n")
+            rc, out, err, mpush = self._drive(cfg, track, shared, ["my-feature"])
+            self.assertEqual(rc, 1)
+            self.assertIn("already exists", err)
+            self.assertTrue(priv.exists())  # private not removed on abort
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,22 @@
+"""in-progress is dispatchable + documented (#271)."""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+import work_plan
+
+
+class RegisterInProgressTest(unittest.TestCase):
+    def test_in_subcommands(self):
+        self.assertEqual(work_plan.SUBCOMMANDS["in-progress"], "commands.in_progress")
+
+    def test_in_descriptions(self):
+        names = {row[0] for row in work_plan.DESCRIPTIONS}
+        self.assertIn("in-progress", names)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -106,5 +106,53 @@ class RenderTrackRowTest(unittest.TestCase):
         self.assertNotIn("(P3, open, ", row)
 
 
+class RenderInProgressTest(unittest.TestCase):
+    def _block(self, next_up):
+        return {
+            "name": "alpha", "operational_status": "active", "launch_priority": "P2",
+            "milestone_alignment": "—", "last_touched_label": "1d ago",
+            "last_handoff_label": "1d ago", "next_up": next_up,
+            "next_up_stale_closed_count": 0, "track_slug": "alpha",
+            "active_branches": [], "new_issues": [], "blockers": [],
+            "drift_items": [], "closure_ready": False, "closure_signals_summary": None,
+        }
+
+    def test_in_progress_item_marked(self):
+        row = render_track_row(self._block([
+            {"number": 271, "title": "x", "priority": "P1", "state": "open",
+             "milestone": None, "in_progress": True},
+        ]))
+        self.assertIn("in-progress", row)
+        self.assertIn("#271", row)
+
+    def test_non_in_progress_item_not_marked(self):
+        row = render_track_row(self._block([
+            {"number": 9, "title": "y", "priority": "P2", "state": "open",
+             "milestone": None, "in_progress": False},
+        ]))
+        self.assertNotIn("in-progress", row)
+
+
+class RenderBlockedByTest(unittest.TestCase):
+    def _block(self, item):
+        return {"name": "alpha", "operational_status": "active", "launch_priority": "P2",
+                "milestone_alignment": "—", "last_touched_label": "1d", "last_handoff_label": "1d",
+                "next_up": [item], "next_up_stale_closed_count": 0, "track_slug": "alpha",
+                "active_branches": [], "new_issues": [], "blockers": [],
+                "drift_items": [], "closure_ready": False, "closure_signals_summary": None}
+
+    def _item(self, blocked):
+        return {"number": 5, "title": "x", "priority": "P1", "state": "open",
+                "milestone": None, "in_progress": False, "blocked_by_display": blocked}
+
+    def test_blocked_by_annotation_rendered(self):
+        row = render_track_row(self._block(self._item(["#9"])))
+        self.assertIn("blocked by #9", row)
+
+    def test_no_annotation_when_empty(self):
+        row = render_track_row(self._block(self._item([])))
+        self.assertNotIn("blocked by", row)
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -75,3 +75,63 @@ class SetFieldTest(unittest.TestCase):
         self.assertEqual(rc, 0)
         mw.assert_not_called()
         self.assertIn("needs_confirm", out)
+
+
+class SetFieldPlanTest(unittest.TestCase):
+    """`set <track> plan=<rel>` — the #285 track↔plan frontmatter link."""
+
+    def _track(self, folder="demo", meta=None):
+        return SimpleNamespace(
+            name="ph", repo="o/r", folder=folder, path=Path("/tmp/ph.md"),
+            has_frontmatter=True, meta=meta if meta is not None else {"status": "active"},
+            body="# b")
+
+    def _drive_plan(self, args, track, cfg=None):
+        base_cfg = {"notes_root": "/tmp"}
+        if cfg:
+            base_cfg.update(cfg)
+        with patch("commands.set_field.load_config", return_value=base_cfg), \
+             patch("commands.set_field.discover_tracks", return_value=[track]), \
+             patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+             patch("commands.set_field.resolve_local_path_for_folder", return_value=None), \
+             patch("commands.set_field.write_file") as mw:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = set_field.run(args)
+        return rc, mw, buf.getvalue()
+
+    def test_sets_plan_path(self):
+        t = self._track()
+        rc, mw, out = self._drive_plan(["ph", "plan=docs/plans/p.md"], t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertEqual(mw.call_args[0][1]["plan"], "docs/plans/p.md")
+
+    def test_empty_plan_clears_link(self):
+        t = self._track(meta={"status": "active", "plan": "docs/plans/old.md"})
+        rc, mw, out = self._drive_plan(["ph", "plan="], t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertNotIn("plan", mw.call_args[0][1])  # key removed, not written as ""
+        self.assertIn("cleared", out)
+
+    def test_unresolved_plan_path_warns_but_saves(self):
+        # local path exists but the file doesn't -> WARN on stderr, still writes.
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            t = self._track()
+            with patch("commands.set_field.load_config", return_value={"notes_root": "/tmp"}), \
+                 patch("commands.set_field.discover_tracks", return_value=[t]), \
+                 patch("lib.write_guard.repo_visibility", return_value="PRIVATE"), \
+                 patch("commands.set_field.resolve_local_path_for_folder",
+                       return_value=Path(d)), \
+                 patch("commands.set_field.write_file") as mw:
+                err = io.StringIO()
+                from contextlib import redirect_stderr
+                buf = io.StringIO()
+                with redirect_stdout(buf), redirect_stderr(err):
+                    rc = set_field.run(["ph", "plan=docs/plans/missing.md"])
+            self.assertEqual(rc, 0)
+            mw.assert_called_once()
+            self.assertEqual(mw.call_args[0][1]["plan"], "docs/plans/missing.md")
+            self.assertIn("does not resolve", err.getvalue())

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

@@ -513,5 +513,85 @@ class OrientRepoFlagTest(unittest.TestCase):
         self.assertIn("ambiguous", out.lower())
 
 
+class OrientInProgressTest(unittest.TestCase):
+    def test_next_pick_marked_in_progress(self):
+        from types import SimpleNamespace
+        track = SimpleNamespace(
+            name="alpha", repo="o/r", local_path=Path("/repo"), path=Path("/n/alpha.md"),
+            body="", meta={"track": "alpha", "launch_priority": "P1",
+                           "milestone_alignment": "—",
+                           "github": {"issues": [271]}, "next_up": [271]})
+        issue = {"number": 271, "title": "x", "state": "open", "labels": [], "milestone": None}
+        with mock.patch("commands.where_was_i.fetch_issues", return_value=[issue]), \
+             mock.patch("commands.where_was_i.hot_issue_numbers", return_value={271}), \
+             mock.patch("commands.where_was_i.current_branch", return_value=None), \
+             mock.patch("commands.where_was_i.find_new_issues_for_tracks", return_value={}):
+            out = io.StringIO()
+            with redirect_stdout(out):
+                where_was_i._orient_track(track)
+        self.assertIn("in-progress", out.getvalue())
+
+
+class OrientBlockedByTest(unittest.TestCase):
+    def test_next_pick_shows_blocked_by(self):
+        from types import SimpleNamespace
+        track = SimpleNamespace(name="alpha", repo="o/r", local_path=None,
+                                path=Path("/n/alpha.md"), body="",
+                                meta={"track": "alpha", "launch_priority": "P1",
+                                      "milestone_alignment": "—",
+                                      "github": {"issues": [5]}, "next_up": [5], "blockers": []})
+        issue = {"number": 5, "title": "x", "state": "open", "labels": [],
+                 "blocked_by": [{"number": 9, "repo": "o/r", "title": "dep"}], "blocking": []}
+        with mock.patch("commands.where_was_i.fetch_issues", return_value=[issue]), \
+             mock.patch("commands.where_was_i.hot_issue_numbers", return_value=set()), \
+             mock.patch("commands.where_was_i.current_branch", return_value=None), \
+             mock.patch("commands.where_was_i.find_new_issues_for_tracks", return_value={}):
+            out = io.StringIO()
+            with redirect_stdout(out):
+                from commands import where_was_i
+                where_was_i._orient_track(track)
+        self.assertIn("blocked by #9", out.getvalue())
+
+    def _orient_with_blocked_by(self, blocked_by, blockers):
+        from types import SimpleNamespace
+        track = SimpleNamespace(name="alpha", repo="o/r", local_path=None,
+                                path=Path("/n/alpha.md"), body="",
+                                meta={"track": "alpha", "launch_priority": "P1",
+                                      "milestone_alignment": "—",
+                                      "github": {"issues": [5]}, "next_up": [5],
+                                      "blockers": blockers})
+        issue = {"number": 5, "title": "x", "state": "open", "labels": [],
+                 "blocked_by": blocked_by, "blocking": []}
+        with mock.patch("commands.where_was_i.fetch_issues", return_value=[issue]), \
+             mock.patch("commands.where_was_i.hot_issue_numbers", return_value=set()), \
+             mock.patch("commands.where_was_i.current_branch", return_value=None), \
+             mock.patch("commands.where_was_i.find_new_issues_for_tracks", return_value={}):
+            out = io.StringIO()
+            with redirect_stdout(out):
+                from commands import where_was_i
+                where_was_i._orient_track(track)
+        return out.getvalue()
+
+    def test_cross_repo_blocked_by_shows_qualified_ref(self):
+        # A cross-repo edge renders owner/repo#N, not a bare #N.
+        out = self._orient_with_blocked_by(
+            [{"number": 9, "repo": "other/repo", "title": "dep"}], [])
+        self.assertIn("blocked by other/repo#9", out)
+
+    def test_same_repo_edge_in_manual_blockers_is_suppressed(self):
+        # A same-repo edge whose number is a manual blocker is owned by the
+        # "Blocker:" line, so it is not re-annotated.
+        out = self._orient_with_blocked_by(
+            [{"number": 9, "repo": "o/r", "title": "dep"}], [9])
+        self.assertNotIn("blocked by", out)
+
+    def test_cross_repo_edge_not_suppressed_by_same_number_blocker(self):
+        # A manual blocker #9 means o/r#9; a cross-repo other/repo#9 is a
+        # different issue and must still be annotated.
+        out = self._orient_with_blocked_by(
+            [{"number": 9, "repo": "other/repo", "title": "dep"}], [9])
+        self.assertIn("blocked by other/repo#9", out)
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/work_plan.py

@@ -51,7 +51,13 @@ SUBCOMMANDS = {
     "--hygiene": "commands.hygiene",      # flag-style alias
     "plan-status": "commands.plan_status",
     "--plan-status": "commands.plan_status",  # flag-style alias
+    "plan-confirm": "commands.plan_confirm",
+    "plan-ack": "commands.plan_ack",
+    "plan-baseline": "commands.plan_baseline",
+    "close-issue": "commands.close_issue",
+    "in-progress": "commands.in_progress",
     "export": "commands.export",
+    "auth-status": "commands.auth_status",
     "list-open-issues": "commands.list_open_issues",
     "set": "commands.set_field",
     "new-track": "commands.new_track",
@@ -59,6 +65,7 @@ SUBCOMMANDS = {
     "set-notes-root": "commands.set_notes_root",
     "notes-vcs": "commands.notes_vcs",
     "plan-branch": "commands.plan_branch",
+    "push-track": "commands.push_track",
 }
 
 DESCRIPTIONS = [
@@ -147,6 +154,10 @@ DESCRIPTIONS = [
      "Emit the viewer-ready JSON read surface (schema 1): every frontmatter'd track with repo, tier, status, visibility, blockers, next_up, an open/closed rollup, and per-issue state/assignee/milestone. Read-only; derives live from gh. Consumed by the VS Code extension.",
      "When a tool (the VS Code viewer, or any script) needs structured track state instead of the human-facing brief/orient text.",
      "/work-plan export --json"),
+    ("auth-status", "[--json]",
+     "Report whether `gh` is installed and authenticated to GitHub. Read-only probe (`gh auth status`) — the toolkit's GitHub reads/writes all go through gh, and the fetch helpers return empty rather than erroring, so an unauthenticated session otherwise looks like an empty-but-working one. `--json` emits {gh_present, authenticated, user, error}; exit code: 0 authenticated, 1 gh present but not logged in, 2 gh not found. The VS Code viewer calls this at activation to fast-fail with a sign-in path instead of a misleadingly empty tree.",
+     "When you (or the viewer) need to know up front whether GitHub calls will work, instead of discovering it via empty results.",
+     "/work-plan auth-status --json"),
     ("list-open-issues", "--repo=<owner/name> [--exclude=<csv-issue-numbers>]",
      "Emit a repo's OPEN issues as JSON ({repo, issues:[{number,title,state,assignee,milestone}]}) — the same issue shape as export. Read-only; derives live from gh. --repo takes a bare org/repo slug; --exclude drops the given issue numbers (the viewer passes a track's current issues so already-slotted ones don't reappear). Unlike export's `untracked`, this includes issues tracked by OTHER tracks, since those are valid slot targets.",
      "When the VS Code viewer's Slot command needs the repo's open issues as a pick-list (the per-track export can't supply issues not yet in the track).",
@@ -167,6 +178,26 @@ DESCRIPTIONS = [
      "Reach a verdict on every plan/spec doc in a repo by correlating each plan's declared file-manifest (Create/Modify/Test paths) against the filesystem + git — not the unreliable checkboxes. Read-only: reports ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less. --json for machine output. Add --stamp to write each verdict into its doc as an idempotent status header (--draft previews without writing). Add --llm for a two-step AI pass that judges prose/ambiguous docs (writes a prompt; you save JSON to the cache; re-run with --llm --apply). --archive moves dead plans to archive/abandoned/ (gated); --issues opens a GitHub issue per partial plan listing its unsatisfied files (gated). Both honor --draft.",
      "When you point at a repo and need to know what's actually done vs. half-done vs. dead among accumulated plans. Run from inside the repo, or use --repo=<key> for a configured one.",
      "/work-plan plan-status --repo=myproject"),
+    ("plan-confirm", "--repo=<key> --verdict=shipped|partial|dead [--clear] [--confirm=<token>] -- <rel>",
+     "Affirm a human verdict on ONE plan/spec doc by writing `verdict_override` into its YAML frontmatter — FRONTMATTER-ONLY (never the body, manifest, checkboxes, or status banner) (#286). plan-status then pins that verdict over the mechanical one and silences the 'shipped but boxes unchecked' lie-gap. Use when a plan genuinely shipped but its phase checkboxes were never ticked, so the red lie-gap X is a false alarm. `<rel>` is the repo-relative doc path from `plan-status --json`. On a PUBLIC repo it prints a confirm heads-up + token and exits (re-run with --confirm=<token>) — the VS Code viewer surfaces this as a modal. --clear removes the override.",
+     "When the Plans view flags a genuinely-done plan with a lie-gap (red X) only because nobody ticked its checkboxes — confirm it instead of hand-ticking 24 boxes.",
+     "/work-plan plan-confirm --repo=myproject --verdict=shipped -- docs/superpowers/plans/2026-03-16-idea-mode-ui.md"),
+    ("plan-ack", "--repo=<key> [--clear] [--confirm=<token>] -- <rel>",
+     "Persist an acknowledgment into ONE plan/spec doc's YAML **frontmatter only** (`acknowledged: true`) — never the body/manifest/checkboxes/banner (#286). Unlike the VS Code viewer's default ack (per-machine, ephemeral `workspaceState`), this is durable + shared: it's committed with the repo, and `plan-status` reads it back to demote the doc. `<rel>` is the repo-relative doc path. Public-repo gated (prints `needs_confirm` + token; re-run with `--confirm=<token>`). `--clear` removes it.",
+     "When you want a 'stop flagging this plan' that sticks across machines and teammates, not just on your laptop.",
+     "/work-plan plan-ack --repo=myproject -- docs/superpowers/plans/2026-03-16-idea-mode-ui.md"),
+    ("plan-baseline", "--repo=<key> [--clear] [--confirm=<token>] -- <rel>",
+     "Stamp the CURRENT computed verdict into ONE plan/spec doc's YAML **frontmatter only** as a drift baseline (`verdict_baseline`) (#286). Distinct from `plan-confirm` (a human pin) and the body banner. `plan-status` then flags **drift** when the live verdict diverges from the baseline — catching a once-shipped plan that silently regressed (its declared files were deleted/moved). The baseline value is computed authoritatively here. Public-repo gated; `--clear` removes it. `verdict_override`, if present, suppresses drift.",
+     "When you want a tripwire on a plan you believe is done: stamp its baseline, and get alerted if it later regresses.",
+     "/work-plan plan-baseline --repo=myproject -- docs/superpowers/plans/2026-03-16-idea-mode-ui.md"),
+    ("close-issue", "--repo=<key|slug> [--reason=completed|not_planned] [--comment=<text>] -- <number>",
+     "⚠️ A GitHub-mutating command (others: `in-progress`, `plan-status --issues`) — closes a GitHub issue via `gh issue close` (most of the toolkit is read-only on GitHub). PRs merged to `dev` don't auto-close issues (GitHub auto-closes only from the default branch), so done-but-OPEN issues pile up; this closes one. `--reason` maps to GitHub's completed/not-planned; `--comment` posts a closing note. `--repo` takes a config key or an org/repo slug. The VS Code viewer gates this behind a mandatory 'Close on GitHub?' modal on every close.",
+     "When an issue is actually done but stayed open because its PR merged to dev, not main — close it without leaving the editor.",
+     "/work-plan close-issue --repo=stylusnexus/work-plan-toolkit --reason=completed --comment='Closed via dev merge' -- 287"),
+    ("in-progress", "<n> [--clear] [--repo=<key|slug>] [--confirm=<token>]",
+     "Mark a tracked GitHub issue as in-progress by adding the `work-plan:in-progress` label (or remove it with --clear). Repo-scoped: resolves <n> to the one tracked repo that lists it, or pass --repo to disambiguate. The label is auto-created. Writes into a PUBLIC repo only with a confirm token (prints {needs_confirm, token} otherwise — the VS Code viewer surfaces it as a modal). brief/orient/the viewer also derive in-progress for free from a hot feat/<n>- or fix/<n>- branch.",
+     "When you start actively working an issue that has no hot branch yet (a hot branch is detected automatically), or to clear the flag when you stop.",
+     "/work-plan in-progress 271"),
     ("set-notes-root", "<path>",
      "Update notes_root in ~/.claude/work-plan/config.yml to an absolute path. Creates the target directory if absent. Prints a WARN if existing frontmatter'd tracks live at the old location (they won't be moved — manual migration required). Non-interactive: safe to call from a GUI or script.",
      "VS Code viewer cold-start: user has picked a folder for their private track notes and the extension invokes this to persist the choice. Also useful on the CLI to relocate notes without hand-editing config.yml.",
@@ -179,6 +210,10 @@ DESCRIPTIONS = [
      "Set up and share a repo's canonical SHARED-tier plan branch (#260). The shared `.work-plan/` tier is pinned to ONE per-repo `plan_branch`, read/written through a dedicated git worktree, so planning never diverges across code branches or pollutes PR / deploy diffs. `init <repo>` creates that branch + a `.work-plan/` skeleton (default an ORPHAN `work-plan/plan`, zero shared history with code like gh-pages; override with --branch) and records `plan_branch` in config — or CONNECTS to a teammate's already-published branch if one exists. init is LOCAL ONLY (no push). `status <repo>` reports whether the branch exists, is published to origin, and how many commits are unpushed (--json for the machine shape). `push <repo>` shares it: on a PUBLIC repo it prints a confirm heads-up + token and exits (re-run with --confirm=<token>); --dry-run previews the commits that would push. Requires a repo registered via init-repo with a local clone path.",
      "ONE-TIME per repo when you want the shared plan to live on its own branch (off dev/main) so planning churn never lands in feature PRs or the deploy diff — yet the CLI + VS Code viewer always show the canonical plan from any checkout. `push` is the deliberate step that shares it with teammates.",
      "/work-plan plan-branch init work-plan-toolkit"),
+    ("push-track", "<track | track@repo> [--repo=<key>] [--no-push] [--confirm=<token>]",
+     "Promote a PRIVATE track (local-only, in notes_root) to the repo's SHARED tier and publish it (#306). Moves the track's `.md` into the repo's `.work-plan/` (on its `plan_branch`, via a worktree), removes the private copy so it isn't duplicated, commits to the plan branch, and pushes — unless `--no-push` (keeps it local). The tier is derived from location, so this is a file move, not a frontmatter edit. Requires the repo to have a local clone + a `plan_branch` (else hints `plan-branch init`). Pushing to a PUBLIC repo makes the track world-visible, so the push is confirm-token gated (prints `needs_confirm` + token; re-run with `--confirm=<token>`).",
+     "When a private track is ready to share with teammates — promote it to the shared plan branch in one step instead of hand-moving the file.",
+     "/work-plan push-track my-feature --repo=myproject"),
 ]
 
 
@@ -268,7 +303,7 @@ def main(argv: list[str]) -> int:
 # (Flag aliases like --brief/--plan-status normalise by stripping leading dashes.)
 _READONLY_SUBCOMMANDS = frozenset({
     "brief", "orient", "where-was-i", "list", "coverage", "duplicates",
-    "plan-status", "export", "list-open-issues", "notes-vcs",
+    "plan-status", "export", "list-open-issues", "auth-status", "notes-vcs",
     # 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",