@stylusnexus/work-plan 2026.6.24 → 2026.7.10

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

@@ -139,6 +139,14 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "folder": getattr(t, "folder", None),
             "tier": getattr(t, "tier", "private") or "private",
             "status": t.meta.get("status"),
+            # True for a track in the archive tier (#328), surfaced only when
+            # export ran with --include-archived; the viewer greys these.
+            "archived": bool(t.meta.get("archived")),
+            # Cleanup earmark (#328): a lightweight "candidate for retirement"
+            # flag set via `mark-cleanup`, with an optional free-text reason
+            # (null when unset). Surfaced by the viewer + hygiene callout.
+            "cleanup_candidate": bool(t.meta.get("cleanup_candidate")),
+            "cleanup_reason": t.meta.get("cleanup_reason"),
             "launch_priority": t.meta.get("launch_priority"),
             "milestone_alignment": milestone_alignment,
             "visibility": visibility.get(t.repo),

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

@@ -378,3 +378,13 @@ def git_mv(src_rel: str, dst_rel: str, repo_path: Path) -> bool:
     (Path(repo_path) / dst_rel).parent.mkdir(parents=True, exist_ok=True)
     proc = _git(repo_path, "mv", src_rel, dst_rel)
     return proc is not None and proc.returncode == 0
+
+
+def git_rm(rel_path: str, repo_path: Path) -> bool:
+    """git-rm `rel_path` (repo-relative) — stage its deletion. Returns True on
+    success. The removal stays in the index (undoable from git history) until
+    the caller commits; #330 delete-track uses it for tracked tracks."""
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = _git(repo_path, "rm", rel_path)
+    return proc is not None and proc.returncode == 0

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

@@ -90,3 +90,19 @@ def render_track_row(t: dict) -> str:
 def render_archived_reopen(repo: str, slug: str, issue: dict) -> str:
     return (f"⚠  archive/{slug}.md (shipped) — new issue #{issue['number']} "
             f"matches this slug. Re-open or slot into a different track?")
+
+
+def render_cleanup_callout(candidates: list) -> str:
+    """Render the hygiene "marked for cleanup" section, or "" if none.
+
+    `candidates` is a list of (name, reason) tuples; reason may be None/empty.
+    Returns a multi-line block (header + one line per track) or an empty string
+    when nothing is marked, so the caller can skip printing entirely.
+    """
+    if not candidates:
+        return ""
+    lines = ["🧹 Marked for cleanup:"]
+    for name, reason in candidates:
+        suffix = f" — {reason}" if reason else ""
+        lines.append(f"    {name}{suffix}")
+    return "\n".join(lines)

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

@@ -128,5 +128,57 @@ class MoveToArchiveTest(unittest.TestCase):
             mv.assert_not_called()
 
 
+class RestoreFromArchiveTest(unittest.TestCase):
+    def _archived_repo(self, d):
+        root = Path(d)
+        (root / "docs/plans/archive/shipped").mkdir(parents=True)
+        (root / "docs/plans/archive/shipped/x.md").write_text("# x")
+        return root
+
+    def test_tracked_restore_calls_git_mv_to_original_dir(self):
+        """Tracked archived file → staged git mv back out → 'restored'."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._archived_repo(d)
+            with mock.patch("lib.archive.git_state.is_tracked", return_value=True), \
+                 mock.patch("lib.archive.git_state.git_mv", return_value=True) as mv:
+                outcome = archive_lib.restore_from_archive(
+                    "docs/plans/archive/shipped/x.md", root)
+            self.assertEqual(outcome, "restored")
+            mv.assert_called_once_with(
+                "docs/plans/archive/shipped/x.md", "docs/plans/x.md", root)
+
+    def test_untracked_restore_local_via_filesystem(self):
+        """Untracked archived file → shutil.move back → 'restored_local'; moves on disk."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._archived_repo(d)
+            with mock.patch("lib.archive.git_state.is_tracked", return_value=False), \
+                 mock.patch("lib.archive.git_state.git_mv") as mv:
+                outcome = archive_lib.restore_from_archive(
+                    "docs/plans/archive/shipped/x.md", root)
+            self.assertEqual(outcome, "restored_local")
+            mv.assert_not_called()
+            self.assertFalse((root / "docs/plans/archive/shipped/x.md").exists())
+            self.assertTrue((root / "docs/plans/x.md").exists())
+
+    def test_collision_refuses_when_live_doc_exists(self):
+        """A live doc already at the destination → 'skipped_collision', no move."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._archived_repo(d)
+            (root / "docs/plans/x.md").write_text("# live already")
+            with mock.patch("lib.archive.git_state.is_tracked") as is_tracked, \
+                 mock.patch("lib.archive.git_state.git_mv") as mv:
+                outcome = archive_lib.restore_from_archive(
+                    "docs/plans/archive/shipped/x.md", root)
+            self.assertEqual(outcome, "skipped_collision")
+            is_tracked.assert_not_called()
+            mv.assert_not_called()
+
+    def test_not_under_archive_returns_none(self):
+        """A path not under archive/<kind>/ → None (nothing to restore)."""
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            self.assertIsNone(archive_lib.restore_from_archive("docs/plans/x.md", root))
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -0,0 +1,100 @@
+"""archive-track / unarchive-track commands (offline; move primitives mocked)."""
+import io
+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 archive_track, unarchive_track
+from lib.write_guard import make_token
+
+
+def _t(name="ph", repo="o/r", path="/tmp/notes/proj/ph.md", tier="private"):
+    return SimpleNamespace(name=name, repo=repo, path=Path(path), tier=tier,
+                           folder="proj", has_frontmatter=True, meta={"status": "active"})
+
+
+class ArchiveTrackTest(unittest.TestCase):
+    def _drive(self, args, track=None, outcome="archived", vis="PRIVATE"):
+        track = track or _t()
+        with patch("commands.archive_track.load_config", return_value={"notes_root": "/tmp/notes"}), \
+             patch("commands.archive_track.discover_tracks", return_value=[track]), \
+             patch("lib.write_guard.repo_visibility", return_value=vis), \
+             patch("commands.archive_track.move_to_archive", return_value=outcome) as mv:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = archive_track.run(args)
+        return rc, mv, buf.getvalue()
+
+    def test_archives_private_track(self):
+        rc, mv, out = self._drive(["ph"])
+        self.assertEqual(rc, 0)
+        mv.assert_called_once_with("ph.md", Path("/tmp/notes/proj"), "parked")
+        self.assertIn("archived", out)
+
+    def test_shared_track_prints_push_hint(self):
+        rc, mv, out = self._drive(["ph"], track=_t(tier="shared"))
+        self.assertEqual(rc, 0)
+        self.assertIn("commit & push", out)
+
+    def test_collision_is_reported_not_errored(self):
+        rc, mv, out = self._drive(["ph"], outcome="skipped_collision")
+        self.assertEqual(rc, 0)
+        self.assertIn("already exists", out)
+
+    def test_hard_failure_returns_1(self):
+        rc, mv, out = self._drive(["ph"], outcome=None)
+        self.assertEqual(rc, 1)
+
+    def test_public_blocks_without_confirm(self):
+        rc, mv, out = self._drive(["ph"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mv.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_public_with_confirm_archives(self):
+        tok = make_token("o/r", "ph")
+        rc, mv, out = self._drive(["ph", f"--confirm={tok}"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mv.assert_called_once()
+
+
+class UnarchiveTrackTest(unittest.TestCase):
+    def _drive(self, args, track=None, outcome="restored", vis="PRIVATE"):
+        track = track or _t(path="/tmp/notes/proj/archive/parked/ph.md")
+        with patch("commands.unarchive_track.load_config", return_value={"notes_root": "/tmp/notes"}), \
+             patch("commands.unarchive_track.discover_archived_tracks", return_value=[track]), \
+             patch("lib.write_guard.repo_visibility", return_value=vis), \
+             patch("commands.unarchive_track.restore_from_archive", return_value=outcome) as rs:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = unarchive_track.run(args)
+        return rc, rs, buf.getvalue()
+
+    def test_restores_from_archive_with_correct_rel_and_base(self):
+        rc, rs, out = self._drive(["ph"])
+        self.assertEqual(rc, 0)
+        rs.assert_called_once_with("archive/parked/ph.md", Path("/tmp/notes/proj"))
+        self.assertIn("restored", out)
+
+    def test_collision_reported(self):
+        rc, rs, out = self._drive(["ph"], outcome="skipped_collision")
+        self.assertEqual(rc, 0)
+        self.assertIn("already exists", out)
+
+    def test_not_found_returns_1(self):
+        with patch("commands.unarchive_track.load_config", return_value={"notes_root": "/tmp/notes"}), \
+             patch("commands.unarchive_track.discover_archived_tracks", return_value=[]):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = unarchive_track.run(["nope"])
+        self.assertEqual(rc, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,36 @@
+"""#417 — brief must not crash when next_up mixes issue numbers and string tokens.
+
+`sorted(set(issue_nums) | set(stored_next_up))` raised
+`TypeError: '<' not supported between instances of 'str' and 'int'` for any track
+whose `next_up` held a non-issue token (e.g. an epic name like `golden-path-v2`)
+next to issue numbers. `_numeric_refs` unions the ref lists, drops non-int tokens
+(they aren't fetchable issues), and sorts what remains.
+"""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands.brief import _numeric_refs
+
+
+class NumericRefsTest(unittest.TestCase):
+    def test_mixed_str_and_int_does_not_crash_and_drops_tokens(self):
+        # The exact shape that crashed live: a string epic token beside numbers.
+        result = _numeric_refs([6012, 6015], ["golden-path-v2", 5996, 5979])
+        self.assertEqual(result, [5979, 5996, 6012, 6015])
+
+    def test_dedupes_across_lists(self):
+        self.assertEqual(_numeric_refs([100, 200], [200, 300]), [100, 200, 300])
+
+    def test_handles_none_and_empty(self):
+        self.assertEqual(_numeric_refs(None, []), [])
+
+    def test_all_string_tokens_yield_empty(self):
+        self.assertEqual(_numeric_refs(["golden-path-v2", "epic-x"]), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,108 @@
+"""delete-track (offline; git mocked). Verifies the destructive-but-bounded
+behavior AND the never-touch-GitHub guarantee."""
+import io
+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 delete_track
+from lib.write_guard import make_token
+
+
+def _t(name="ph", repo="o/r", path="/tmp/notes/proj/ph.md", tier="private"):
+    return SimpleNamespace(name=name, repo=repo, path=Path(path), tier=tier,
+                           folder="proj", has_frontmatter=True, meta={"status": "active"})
+
+
+def _drive(args, track=None, vis="PRIVATE", tracked=True, git_rm_ok=True,
+           archived=None):
+    track = track or _t()
+    with patch("commands.delete_track.load_config", return_value={"notes_root": "/tmp/notes"}), \
+         patch("commands.delete_track.discover_tracks", return_value=[track]), \
+         patch("commands.delete_track.discover_archived_tracks", return_value=archived or []), \
+         patch("lib.write_guard.repo_visibility", return_value=vis), \
+         patch("commands.delete_track.git_state.is_tracked", return_value=tracked), \
+         patch("commands.delete_track.git_state.git_rm", return_value=git_rm_ok) as grm, \
+         patch("pathlib.Path.unlink") as unlink:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = delete_track.run(args)
+    return rc, grm, unlink, buf.getvalue()
+
+
+class DeleteTrackTest(unittest.TestCase):
+    def test_private_tracked_git_rm_and_undo_message(self):
+        rc, grm, unlink, out = _drive(["ph"])
+        self.assertEqual(rc, 0)
+        grm.assert_called_once_with("ph.md", Path("/tmp/notes/proj"))
+        unlink.assert_not_called()
+        self.assertIn("deleted track", out)
+        self.assertIn("GitHub issues are untouched", out)
+        self.assertIn("Recoverable via notes-vcs", out)
+
+    def test_shared_tracked_prints_commit_push(self):
+        rc, grm, unlink, out = _drive(["ph"], track=_t(tier="shared"))
+        self.assertEqual(rc, 0)
+        grm.assert_called_once()
+        self.assertIn("commit & push", out)
+
+    def test_untracked_uses_filesystem_unlink_and_warns_permanent(self):
+        # notes-vcs off (untracked) → unlink → the message must say PERMANENT,
+        # NOT promise notes-vcs undo (the review's borderline-critical finding).
+        rc, grm, unlink, out = _drive(["ph"], tracked=False)
+        self.assertEqual(rc, 0)
+        grm.assert_not_called()
+        unlink.assert_called_once()
+        self.assertIn("PERMANENT", out)
+        self.assertNotIn("Recoverable via notes-vcs", out)
+
+    def test_private_tracked_message_is_recoverable_not_permanent(self):
+        # notes-vcs on (tracked) → git rm → recoverable, and NOT flagged permanent.
+        rc, grm, unlink, out = _drive(["ph"], tracked=True)
+        self.assertEqual(rc, 0)
+        self.assertIn("Recoverable via notes-vcs", out)
+        self.assertNotIn("PERMANENT", out)
+
+    def test_git_rm_failure_returns_1(self):
+        rc, grm, unlink, out = _drive(["ph"], git_rm_ok=False)
+        self.assertEqual(rc, 1)
+
+    def test_public_blocks_without_confirm(self):
+        rc, grm, unlink, out = _drive(["ph"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        grm.assert_not_called()
+        unlink.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_public_with_confirm_deletes(self):
+        tok = make_token("o/r", "ph")
+        rc, grm, unlink, out = _drive(["ph", f"--confirm={tok}"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        grm.assert_called_once()
+
+    def test_not_found_returns_1(self):
+        with patch("commands.delete_track.load_config", return_value={"notes_root": "/tmp"}), \
+             patch("commands.delete_track.discover_tracks", return_value=[]), \
+             patch("commands.delete_track.discover_archived_tracks", return_value=[]):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = delete_track.run(["nope"])
+        self.assertEqual(rc, 1)
+
+    def test_module_never_touches_github(self):
+        """Guardrail: delete-track must not import a GitHub-mutating helper.
+        The issues outlive the track (#330)."""
+        src = (SKILL_ROOT / "commands" / "delete_track.py").read_text()
+        self.assertNotIn("github_state", src)
+        self.assertNotIn("gh issue", src)
+        self.assertNotIn("subprocess", src)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -38,8 +38,18 @@ class BuildExportTest(unittest.TestCase):
         # Phase 2: next_up_preset must be present in every track
         self.assertIn("next_up_preset", t)
         self.assertEqual(t["next_up_preset"], "flow")  # default when no next_up_order in meta
+        # archived defaults false (active tracks); #328.
+        self.assertFalse(t["archived"])
         json.dumps(out)  # must be serializable
 
+    def test_archived_flag_emitted_when_meta_set(self):
+        """A track tagged archived (the --include-archived union sets meta) exports
+        archived:true so the viewer can grey it (#328)."""
+        tr = _track("old", "o/r", [1])
+        tr.meta["archived"] = True
+        out = build_export([tr], {("o/r", "old"): []}, {"o/r": "PRIVATE"}, now="t")
+        self.assertTrue(out["tracks"][0]["archived"])
+
     def test_path_is_null_when_track_has_no_path(self):
         """A track object without a `path` attribute exports path=None, so the
         viewer disables its open-file affordance instead of erroring (#211)."""
@@ -381,6 +391,37 @@ class BuildExportPlanTest(unittest.TestCase):
         self.assertEqual(out["tracks"][0]["plan"], {"rel": "docs/plans/p.md", "resolved": False})
 
 
+class BuildExportCleanupCandidateTest(unittest.TestCase):
+    """cleanup_candidate / cleanup_reason surface in the export JSON (#328)."""
+
+    def test_cleanup_absent_defaults(self):
+        """A track with no cleanup marker → candidate False, reason None."""
+        tracks = [_track("alpha", "o/r", [1])]
+        out = build_export(tracks, {("o/r", "alpha"): []}, {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertFalse(tr["cleanup_candidate"])
+        self.assertIsNone(tr["cleanup_reason"])
+
+    def test_cleanup_candidate_and_reason_exported(self):
+        """cleanup_candidate: true + cleanup_reason → both surface in export."""
+        t = _track("alpha", "o/r", [1])
+        t.meta["cleanup_candidate"] = True
+        t.meta["cleanup_reason"] = "superseded by v2"
+        out = build_export([t], {("o/r", "alpha"): []}, {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertTrue(tr["cleanup_candidate"])
+        self.assertEqual(tr["cleanup_reason"], "superseded by v2")
+
+    def test_cleanup_candidate_without_reason(self):
+        """Marked but no reason → candidate True, reason None."""
+        t = _track("alpha", "o/r", [1])
+        t.meta["cleanup_candidate"] = True
+        out = build_export([t], {("o/r", "alpha"): []}, {"o/r": "PRIVATE"}, now="t")
+        tr = out["tracks"][0]
+        self.assertTrue(tr["cleanup_candidate"])
+        self.assertIsNone(tr["cleanup_reason"])
+
+
 class BuildExportDependsOnTest(unittest.TestCase):
     """Tests that depends_on is surfaced in the export JSON (#102)."""
 

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

@@ -0,0 +1,88 @@
+# tests/test_mark_cleanup.py
+import io, sys, 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 mark_cleanup
+from lib.write_guard import make_token
+
+
+def _t(name="ph", repo="o/r", meta=None):
+    return SimpleNamespace(name=name, repo=repo, path=Path(f"/tmp/{name}.md"),
+        has_frontmatter=True,
+        meta=meta if meta is not None else {"status": "active", "github": {"repo": repo}},
+        body="# b")
+
+
+def _drive(args, track=None, vis="PRIVATE"):
+    track = track or _t()
+    with patch("commands.mark_cleanup.load_config", return_value={"notes_root": "/tmp"}), \
+         patch("commands.mark_cleanup.discover_tracks", return_value=[track]), \
+         patch("lib.write_guard.repo_visibility", return_value=vis), \
+         patch("commands.mark_cleanup.write_file") as mw:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = mark_cleanup.run(args)
+    return rc, mw, buf.getvalue()
+
+
+class MarkCleanupTest(unittest.TestCase):
+    def test_marks_private_track(self):
+        rc, mw, out = _drive(["ph"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertIs(mw.call_args[0][1]["cleanup_candidate"], True)
+        self.assertIn("marked for cleanup", out)
+
+    def test_marks_with_reason(self):
+        rc, mw, out = _drive(["ph", "--reason=superseded by v2"])
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written = mw.call_args[0][1]
+        self.assertIs(written["cleanup_candidate"], True)
+        self.assertEqual(written["cleanup_reason"], "superseded by v2")
+        self.assertIn("superseded by v2", out)
+
+    def test_clear_removes_both_keys(self):
+        t = _t(meta={"status": "active", "github": {"repo": "o/r"},
+                     "cleanup_candidate": True, "cleanup_reason": "old"})
+        rc, mw, out = _drive(["ph", "--clear"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        written = mw.call_args[0][1]
+        self.assertNotIn("cleanup_candidate", written)
+        self.assertNotIn("cleanup_reason", written)
+        self.assertIn("cleared", out)
+
+    def test_clear_when_only_candidate_present(self):
+        # --clear must not error when only one of the two keys exists.
+        t = _t(meta={"status": "active", "github": {"repo": "o/r"},
+                     "cleanup_candidate": True})
+        rc, mw, out = _drive(["ph", "--clear"], track=t)
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertNotIn("cleanup_candidate", mw.call_args[0][1])
+
+    def test_public_blocks_without_confirm(self):
+        rc, mw, out = _drive(["ph"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_not_called()
+        self.assertIn("needs_confirm", out)
+
+    def test_public_with_valid_confirm_writes(self):
+        tok = make_token("o/r", "ph")
+        rc, mw, out = _drive(["ph", f"--confirm={tok}"], vis="PUBLIC")
+        self.assertEqual(rc, 0)
+        mw.assert_called_once()
+        self.assertIs(mw.call_args[0][1]["cleanup_candidate"], True)
+
+    def test_no_track_arg_is_usage_error(self):
+        rc, mw, out = _drive([])
+        self.assertEqual(rc, 2)
+        mw.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,77 @@
+"""plan-unarchive: restore an archived plan doc (offline; restore primitive
++ repo-root resolution mocked)."""
+import io
+import json
+import sys
+import unittest
+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_unarchive
+
+ARCHIVED = "docs/plans/archive/shipped/p.md"
+
+
+def _drive(args, outcome="restored", is_file=True):
+    with mock.patch("commands.plan_unarchive.plan_status._resolve_repo_root",
+                    return_value=Path("/repo")), \
+         mock.patch("pathlib.Path.is_file", return_value=is_file), \
+         mock.patch("commands.plan_unarchive.archive_lib.restore_from_archive",
+                    return_value=outcome) as rs:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = plan_unarchive.run(args)
+    return rc, rs, buf.getvalue()
+
+
+class PlanUnarchiveTest(unittest.TestCase):
+    def test_restores_and_emits_json(self):
+        rc, rs, out = _drive(["--repo=r", "--yes", "--json", "--", ARCHIVED])
+        self.assertEqual(rc, 0)
+        rs.assert_called_once_with(ARCHIVED, Path("/repo"))
+        obj = json.loads(out)
+        self.assertEqual(obj["action"], "unarchive")
+        self.assertEqual(obj["outcome"], "restored")
+        # dest strips archive/shipped/ back to the live location.
+        self.assertEqual(obj["dest"], "docs/plans/p.md")
+
+    def test_collision_refused(self):
+        rc, rs, out = _drive(["--repo=r", "--yes", "--json", "--", ARCHIVED],
+                             outcome="skipped_collision")
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out)["outcome"], "skipped_collision")
+
+    def test_restored_local(self):
+        rc, rs, out = _drive(["--repo=r", "--yes", "--json", "--", ARCHIVED],
+                             outcome="restored_local")
+        self.assertEqual(json.loads(out)["outcome"], "restored_local")
+
+    def test_draft_previews_without_moving(self):
+        rc, rs, out = _drive(["--repo=r", "--draft", "--", ARCHIVED])
+        self.assertEqual(rc, 0)
+        rs.assert_not_called()
+        self.assertIn("Would restore", out)
+
+    def test_not_under_archive_errors(self):
+        rc, rs, out = _drive(["--repo=r", "--yes", "--", "docs/plans/p.md"])
+        self.assertEqual(rc, 1)
+        rs.assert_not_called()
+
+    def test_missing_file_errors(self):
+        rc, rs, out = _drive(["--repo=r", "--yes", "--", ARCHIVED], is_file=False)
+        self.assertEqual(rc, 1)
+        rs.assert_not_called()
+
+    def test_repo_required(self):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = plan_unarchive.run(["--yes", "--", ARCHIVED])
+        self.assertEqual(rc, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/work-plan/work_plan.py

@@ -54,6 +54,7 @@ SUBCOMMANDS = {
     "--plan-status": "commands.plan_status",  # flag-style alias
     "plan-confirm": "commands.plan_confirm",
     "plan-archive": "commands.plan_archive",
+    "plan-unarchive": "commands.plan_unarchive",
     "plan-ack": "commands.plan_ack",
     "plan-baseline": "commands.plan_baseline",
     "close-issue": "commands.close_issue",
@@ -66,6 +67,10 @@ SUBCOMMANDS = {
     "set-next-up": "commands.set_next_up",
     "new-track": "commands.new_track",
     "rename-track": "commands.rename_track",
+    "mark-cleanup": "commands.mark_cleanup",
+    "archive-track": "commands.archive_track",
+    "unarchive-track": "commands.unarchive_track",
+    "delete-track": "commands.delete_track",
     "set-notes-root": "commands.set_notes_root",
     "notes-vcs": "commands.notes_vcs",
     "plan-branch": "commands.plan_branch",
@@ -186,6 +191,22 @@ DESCRIPTIONS = [
      "Rename an active track's slug: moves the .md file, updates the frontmatter `track` field + last_touched. Resolve <old-slug> with track@repo or --repo when ambiguous. Validates <new-slug> like new-track and rejects a name already taken in the same repo/tier. For shared tracks, --commit stages + commits the move (else prints a 'commit to share' hint). --fix-refs rewrites sibling tracks' depends_on that reference the old slug (otherwise they're just warned about). Gates on public repos — prints {needs_confirm, token} and exits cleanly; re-run with --confirm=<token>.",
      "When a project pivots, a track name turns out misleading, or a slug needs norming — instead of hand-editing the file + frontmatter. Archived tracks are immutable (not renamable).",
      "/work-plan rename-track old-project-name new-project-name"),
+    ("mark-cleanup", "<track | track@repo> [--repo=<key>] [--clear] [--reason=<text>] [--confirm=<token>]",
+     "Flag a track as a cleanup candidate by writing `cleanup_candidate: true` (and an optional `cleanup_reason`) into its frontmatter — a lightweight earmark that `hygiene` surfaces so stale/consolidatable tracks don't get lost. --clear removes both keys. Gates on public repos — prints {needs_confirm, token} and exits cleanly; re-run with --confirm=<token>.",
+     "When you notice a track is stale, superseded, or ready to retire but aren't closing it yet — mark it so the next hygiene pass reminds you.",
+     "/work-plan mark-cleanup old-experiment --reason='superseded by v2'"),
+    ("archive-track", "<track | track@repo> [--repo=<key>] [--confirm=<token>]",
+     "Set a track aside REVERSIBLY: move its .md into archive/parked/ so it drops out of the active views but is kept for reference (distinct from `close`, which is terminal). Git-aware — a shared track archives as a staged `git mv` (commit & push to share), a private one as a filesystem move. Never touches GitHub. Gates on public repos. Restore with unarchive-track.",
+     "When a track is dormant but you don't want to close it — park it out of the active rotation.",
+     "/work-plan archive-track spike-idea"),
+    ("unarchive-track", "<track | track@repo> [--repo=<key>] [--confirm=<token>]",
+     "Restore an archived track (parked/shipped/abandoned) back into the active set — the inverse of archive-track and of `close`'s move. Git-aware staged/local move; never touches GitHub. Gates on public repos.",
+     "When an archived track becomes relevant again — pull it back into the active views.",
+     "/work-plan unarchive-track spike-idea"),
+    ("delete-track", "<track | track@repo> [--repo=<key>] [--confirm=<token>]",
+     "DESTRUCTIVE: remove a track's local .md file. NEVER touches GitHub — the issues it referenced outlive the track. Private tier: the deletion is an undoable notes-vcs commit. Shared tier: a staged `git rm` you commit & push (recoverable from git history until then). Gates on public repos (the VS Code viewer adds a hard modal + type-to-confirm for shared tracks). Prefer archive-track for a reversible set-aside.",
+     "When a track is genuinely dead and you want it gone (not just archived) — its GitHub issues are unaffected.",
+     "/work-plan delete-track abandoned-spike"),
     ("plan-status", "[--repo=<key>] [--json] [--stamp [--draft]] [--llm [--apply]] [--archive | --issues] [--draft] [--since-days=N] [--type=plan|spec]",
      "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.",
@@ -198,6 +219,10 @@ DESCRIPTIONS = [
      "Archive ONE plan/spec doc whose effective verdict is shipped: history-preserving `git mv` into archive/shipped/. Refuses non-shipped docs; skips (never overwrites) a name collision. --draft previews; --yes skips the prompt for non-interactive callers (the VS Code viewer); --json emits a single {action,rel,outcome,dest} object. `<rel>` is the repo-relative doc path from `plan-status --json`.",
      "When a shipped plan clutters the active plans view and you want to move it to archive/shipped/ in one step — with full git history preserved.",
      "/work-plan plan-archive --repo=myproject -- docs/superpowers/plans/2026-03-16-idea-mode-ui.md"),
+    ("plan-unarchive", "--repo=<key> [--draft] [--yes] [--json] -- <rel>",
+     "Restore ONE archived plan/spec doc back OUT of archive/<kind>/ to its live location — the inverse of plan-archive (#388). Refuses (never overwrites) a collision with a live doc of the same name. Git-aware staged/local move. --draft previews; --yes / --json for non-interactive callers. `<rel>` is the archived doc's repo-relative path (from `plan-status --json --include-archived`).",
+     "When a plan was archived by mistake, or a shipped plan needs more work — pull it back into the live plans set without a hand-run git mv.",
+     "/work-plan plan-unarchive --repo=myproject -- docs/superpowers/plans/archive/shipped/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.",