@stylusnexus/work-plan 2026.6.22 → 2026.7.3

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

@@ -1,21 +1,67 @@
-"""The archive move primitive: collision-checked, history-preserving `git mv`
-of a doc into archive/<kind>/. Eligibility (is-this-shipped) is the caller's
-job — this only moves files."""
-from pathlib import Path
+"""The archive move primitive: collision-checked move of a doc into
+archive/<kind>/. For tracked files the move is a history-preserving `git mv`
+(staged rename); for untracked/gitignored files it falls back to a plain
+filesystem move. Eligibility (is-this-shipped) is the caller's job — this
+only moves files."""
+import shutil
+from pathlib import Path, PurePosixPath
 
 from lib import git_state
 from lib import reconcile_actions
 
 
 def move_to_archive(rel: str, repo_root, kind: str):
-    """git-mv `rel` into archive/<kind>/. Returns:
-      "archived"          on a clean move,
-      "skipped_collision" if the destination already exists (never overwrite),
-      None                if git_mv failed for any other reason (hard error).
+    """Move `rel` into archive/<kind>/. Returns:
+      "archived"          tracked file: history-preserving `git mv` (staged rename),
+      "archived_local"    untracked/gitignored file: plain filesystem move,
+      "skipped_collision" destination already exists (never overwrite),
+      None                hard failure (git mv failed on a tracked file, or OSError
+                          on an untracked file).
     """
     dest = reconcile_actions.archive_dest(rel, kind)
     if (Path(repo_root) / dest).exists():
         return "skipped_collision"
-    if git_state.git_mv(rel, dest, repo_root):
-        return "archived"
-    return None
+    if git_state.is_tracked(rel, Path(repo_root)):
+        if git_state.git_mv(rel, dest, repo_root):
+            return "archived"
+        return None
+    # Untracked / gitignored — plain filesystem move.
+    src_path = Path(repo_root) / rel
+    dst_path = Path(repo_root) / dest
+    try:
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src_path), str(dst_path))
+        return "archived_local"
+    except OSError:
+        return None
+
+
+def restore_from_archive(rel: str, repo_root):
+    """Inverse of move_to_archive: move an archived doc back OUT of
+    `.../archive/<kind>/<name>` to its original directory (`.../name`). Returns:
+      "restored"          tracked file: history-preserving `git mv` (staged),
+      "restored_local"    untracked/gitignored file: plain filesystem move,
+      "skipped_collision" a live doc already exists at the destination,
+      None                `rel` isn't under archive/<kind>/, or a hard move failure.
+    Shared by unarchive-track (#328) and plan-unarchive (#388).
+    """
+    p = PurePosixPath(rel)
+    # Expect .../archive/<kind>/<name>; the grandparent dir must be "archive".
+    if p.parent.parent.name != "archive":
+        return None
+    dest = str(p.parent.parent.parent / p.name)
+    if (Path(repo_root) / dest).exists():
+        return "skipped_collision"
+    if git_state.is_tracked(rel, Path(repo_root)):
+        if git_state.git_mv(rel, dest, repo_root):
+            return "restored"
+        return None
+    # Untracked / gitignored — plain filesystem move.
+    src_path = Path(repo_root) / rel
+    dst_path = Path(repo_root) / dest
+    try:
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src_path), str(dst_path))
+        return "restored_local"
+    except OSError:
+        return None

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

@@ -358,6 +358,18 @@ def path_committed_since(rel_path: str, since: date, repo_path: Path) -> bool:
     return proc is not None and proc.returncode == 0 and bool(proc.stdout.strip())
 
 
+def is_tracked(rel_path: str, repo_path: Path) -> bool:
+    """True iff `rel_path` is tracked by git (git ls-files --error-unmatch).
+
+    False for untracked/gitignored paths AND when repo_path isn't a git repo
+    or doesn't exist. Never raises.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = _git(repo_path, "ls-files", "--error-unmatch", rel_path)
+    return proc is not None and proc.returncode == 0
+
+
 def git_mv(src_rel: str, dst_rel: str, repo_path: Path) -> bool:
     """git-mv `src_rel` -> `dst_rel` (both repo-relative), creating the dest
     directory first. Returns True on success. History-preserving."""
@@ -366,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

@@ -1,12 +1,15 @@
 """Pure archive helpers: destination path + shipped-row selection (offline)."""
 import sys
+import tempfile
 import unittest
 from pathlib import Path
+from unittest import mock
 
 SKILL_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(SKILL_ROOT))
 
 from lib import reconcile_actions as ra
+from lib import archive as archive_lib
 
 
 class ArchiveDestTest(unittest.TestCase):
@@ -46,11 +49,6 @@ class ShippedRowsTest(unittest.TestCase):
         self.assertEqual(rels, ["a.md", "b.md"])
 
 
-import tempfile
-from unittest import mock
-from lib import archive as archive_lib
-
-
 class MoveToArchiveTest(unittest.TestCase):
     def _repo(self, d):
         root = Path(d)
@@ -58,32 +56,128 @@ class MoveToArchiveTest(unittest.TestCase):
         (root / "docs/plans/x.md").write_text("# x")
         return root
 
-    def test_archived_calls_git_mv_to_shipped_dir(self):
+    # ------------------------------------------------------------------
+    # tracked path: branches through git_mv
+    # ------------------------------------------------------------------
+
+    def test_tracked_archived_calls_git_mv(self):
+        """Tracked file: is_tracked=True -> git_mv called -> 'archived'."""
         with tempfile.TemporaryDirectory() as d:
             root = self._repo(d)
-            with mock.patch("lib.archive.git_state.git_mv", return_value=True) as mv:
+            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.move_to_archive("docs/plans/x.md", root, "shipped")
             self.assertEqual(outcome, "archived")
             mv.assert_called_once_with(
                 "docs/plans/x.md", "docs/plans/archive/shipped/x.md", root)
 
-    def test_collision_skips_without_calling_git_mv(self):
+    def test_tracked_git_mv_failure_returns_none(self):
+        """Tracked file where git_mv fails -> None (hard error)."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("lib.archive.git_state.is_tracked", return_value=True), \
+                 mock.patch("lib.archive.git_state.git_mv", return_value=False):
+                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertIsNone(outcome)
+
+    # ------------------------------------------------------------------
+    # untracked/gitignored path: plain filesystem move
+    # ------------------------------------------------------------------
+
+    def test_untracked_archived_local_via_filesystem(self):
+        """Untracked file: is_tracked=False -> shutil.move called -> 'archived_local'.
+
+        The file must actually move on disk (src gone, dest exists)."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._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.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertEqual(outcome, "archived_local")
+            mv.assert_not_called()
+            # Source is gone; dest exists.
+            self.assertFalse((root / "docs/plans/x.md").exists())
+            self.assertTrue((root / "docs/plans/archive/shipped/x.md").exists())
+
+    def test_untracked_oserror_returns_none(self):
+        """Untracked file where shutil.move raises OSError -> None."""
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("lib.archive.git_state.is_tracked", return_value=False), \
+                 mock.patch("lib.archive.shutil.move",
+                            side_effect=OSError("permission denied")):
+                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertIsNone(outcome)
+
+    # ------------------------------------------------------------------
+    # collision: checked before tracking branch, git_mv never called
+    # ------------------------------------------------------------------
+
+    def test_collision_skips_without_any_move(self):
+        """Destination already exists -> 'skipped_collision', no move attempted."""
         with tempfile.TemporaryDirectory() as d:
             root = self._repo(d)
             dest = root / "docs/plans/archive/shipped"
             dest.mkdir(parents=True)
             (dest / "x.md").write_text("# already here")
-            with mock.patch("lib.archive.git_state.git_mv") as mv:
+            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.move_to_archive("docs/plans/x.md", root, "shipped")
             self.assertEqual(outcome, "skipped_collision")
+            is_tracked.assert_not_called()
             mv.assert_not_called()
 
-    def test_git_mv_failure_returns_none(self):
+
+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._repo(d)
-            with mock.patch("lib.archive.git_state.git_mv", return_value=False):
-                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
-            self.assertIsNone(outcome)
+            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__":

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_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)."""