@stylusnexus/work-plan 2026.6.22 → 2026.7.3

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_archive.py

@@ -43,7 +43,9 @@ class PlanArchiveTest(unittest.TestCase):
     def test_archives_shipped_with_yes_json(self):
         with tempfile.TemporaryDirectory() as d:
             root = _repo(d, SHIPPED_BODY)
-            with mock.patch("commands.plan_archive.archive_lib.git_state.git_mv",
+            with mock.patch("commands.plan_archive.archive_lib.git_state.is_tracked",
+                            return_value=True), \
+                 mock.patch("commands.plan_archive.archive_lib.git_state.git_mv",
                             return_value=True) as mv:
                 rc, out = _run(root, ["--repo=x", "--yes", "--json",
                                       "--", "docs/plans/p.md"])

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

@@ -29,6 +29,9 @@ class ArchiveTest(unittest.TestCase):
         # run() now reads the batched paths_last_commit_dates map (#391); mock its
         # .get to return the stale date for every doc (path_last_commit_date is the
         # fallback path, mocked too).
+        #
+        # _archive_dead now routes through archive_lib.move_to_archive, so patch
+        # is_tracked + git_mv on lib.archive.git_state (not plan_status.git_state).
         stale = datetime(2026, 1, 1)
         batched = mock.MagicMock()
         batched.get.return_value = stale
@@ -37,7 +40,8 @@ class ArchiveTest(unittest.TestCase):
              mock.patch("commands.plan_status.git_state.paths_last_commit_dates",
                         return_value=batched), \
              mock.patch("commands.plan_status.Path.cwd", return_value=root), \
-             mock.patch("commands.plan_status.git_state.git_mv",
+             mock.patch("lib.archive.git_state.is_tracked", return_value=True), \
+             mock.patch("lib.archive.git_state.git_mv",
                         return_value=mv_ok) as mv, \
              mock.patch("commands.plan_status.prompt_yes_no", return_value=True):
             buf = io.StringIO()

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

@@ -107,7 +107,9 @@ class ArchiveShippedBatchTest(unittest.TestCase):
         # to "no" on non-TTY stdin) and archive, mirroring per-doc plan-archive.
         with tempfile.TemporaryDirectory() as d:
             root = _repo_batch(d)
-            with mock.patch("commands.plan_status.archive_lib.git_state.git_mv",
+            with mock.patch("commands.plan_status.archive_lib.git_state.is_tracked",
+                            return_value=True), \
+                 mock.patch("commands.plan_status.archive_lib.git_state.git_mv",
                             return_value=True) as mv:
                 rc, out = _run(root, ["--archive-shipped", "--yes"])
             self.assertEqual(rc, 0)

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.",