@stylusnexus/work-plan 2026.6.24 → 2026.7.3

package/README.md

@@ -529,6 +529,10 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `remove-repo <key>` | Unregister a repo: delete its block from your config. **Config-only** — the notes folder, any tracks, and the local clone are left untouched (a notes folder or tracks that referenced it are now orphaned and can be removed by hand). Completes the add/update/remove trio with `init-repo`. |
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `rename-track <old-slug \| old@repo> <new-slug> [--repo=<key>] [--fix-refs] [--commit]` | Rename an active track's slug: moves its `.md` file and updates the frontmatter `track` field + `last_touched`. 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 (otherwise it prints a "commit to share" hint). `--fix-refs` rewrites sibling tracks' `depends_on` that reference the old slug; without it they're just warned about. Archived tracks are immutable. Public-repo gated. |
+| `mark-cleanup <track> [--reason=<text>] [--clear] [--confirm] [--repo=<key>]` | Flag a track as a cleanup candidate — writes `cleanup_candidate: true` (+ optional `cleanup_reason`) into its frontmatter, a reversible earmark that `hygiene` surfaces (🧹) so stale tracks aren't lost. `--clear` removes it. Non-destructive; public-repo gated (#329). |
+| `archive-track <track> [--confirm] [--repo=<key>]` | Set a track aside **reversibly**: move its `.md` into `archive/parked/` so it drops out of the active views but is kept (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 (#328). |
+| `unarchive-track <track> [--confirm] [--repo=<key>]` | Restore an archived track (parked/shipped/abandoned) back into the active set — the inverse of `archive-track` and of `close`'s move (#328). |
+| `delete-track <track> [--confirm] [--repo=<key>]` | **DESTRUCTIVE:** remove a track's local `.md`. **Never touches GitHub** — the issues it referenced outlive the track. Private tier: an undoable notes-vcs commit; shared tier: a staged `git rm` to commit & push (recoverable from git history until then). Prefer `archive-track` for a reversible set-aside. The VS Code viewer adds a hard modal + type-to-confirm on shared tracks (#330). |
 | `set-next-up <track> (--preset=<name> \| --order=a,b,c \| --clear \| --auto=on\|off) [--repo=<key>] [--confirm=<token>]` | Configure the ranking preset and/or auto-derivation flag for a track's next_up list. `--preset` sets a named preset: `flow` (default — milestone → dependency → priority → recency), `priority-driven` (priority first, ignores milestone bias, for backlogs with no milestones), `backlog` (oldest issues first — surfaces stalled work), or `custom` (requires `--order`). `--order=a,b,c` sets a custom comma-separated criterion list (`milestone`, `dependency`, `priority`, `recency`, `aging`). `--clear` reverts to the global `next_up_default` config or the default `flow`. `--auto=on` activates `next_up_auto` so brief/orient/export auto-derive the next-up list live from the ranking preset (ignoring the curated list); `--auto=off` clears it to revert to the curated list. `--auto` can be used standalone or combined with `--preset`/`--order`/`--clear`. Writes `next_up_order` and/or `next_up_auto` into the track's frontmatter; does NOT touch the `next_up` issue-list. Global default: add `next_up_default: <preset>` to `~/.claude/work-plan/config.yml`. Public-repo gated. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
 | `notes-vcs <init\|enable\|disable\|status\|undo> [<sha>] [--no-enable] [--json]` | Opt-in **local** version control for the private `notes_root` tier — history/undo for tracks on your machine, never pushed. `init` git-inits `notes_root` as a personal repo (baseline commit of existing tracks) and turns on auto-commit (`--no-enable` skips that). For safety it **refuses** a `notes_root` that already has a git remote or is a repo work-plan didn't create. When on, every track-mutating command (`slot`/`group`/`handoff`/`close`/`set`/…) commits **only the files it changed** (pre-existing uncommitted edits are left alone) as an undoable commit. The shared tier is unaffected — it's versioned by its own repo. `status` shows whether `notes_root` is a repo, whether auto-commit is on, and the last commit (`--json` for the machine shape the VS Code viewer polls). `undo [<sha>]` reverts a commit (default HEAD) — reverses the last edit. |
@@ -544,6 +548,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `plan-status [--repo=<key>] [--json] [--stamp [--draft]] [--llm [--apply]] [--archive \| --issues] [--draft]` | Reach a verdict on every plan/spec doc in a repo by correlating its declared file-manifest against git + the filesystem: ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less / 🧳 foreign. Read-only by default. `--stamp` writes an idempotent status header into each doc (`--draft` previews); `--llm` runs a two-step AI verdict on prose/ambiguous docs; `--archive` moves dead plans to `archive/abandoned/` and `--issues` opens issues for partial plans (both gated, both honor `--draft`); `--json` for machine output. Add `--archive-shipped` to batch-archive every clean shipped doc (lie-gap excluded unless `--include-lie-gap`); `--include-archived` also lists archived docs (tagged `archived`/`archive_kind`) in `--json`. |
 | `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 only** (never the body, checkboxes, manifest, or status banner). `plan-status` then pins that verdict over the mechanical one and silences the "shipped but boxes unchecked" lie-gap. Use when a genuinely-shipped plan is flagged only because its phase checkboxes were never ticked. `<rel>` is the repo-relative doc path. Public-repo gated (`--confirm=<token>`); `--clear` removes the override. |
 | `plan-archive --repo=<key> [--draft] [--yes] [--json] -- <rel>` | 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. The `outcome` distinguishes a **tracked** doc (`archived` — a staged history-preserving `git mv`; commit & push to share it) from a **gitignored/untracked** doc (`archived_local` — a plain filesystem move, not git-tracked), so archive never silently fails on an untracked path (#399). |
+| `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 path (from `plan-status --json --include-archived`). |
 | `plan-ack --repo=<key> [--clear] [--confirm=<token>] -- <rel>` | Persist a **durable acknowledgment** into ONE plan/spec doc's YAML **frontmatter only** (`acknowledged: true`) — a "stop flagging this" that's committed with the repo and shared with teammates, unlike the VS Code viewer's per-machine `workspaceState` ack. `plan-status` reads it back (emits `acknowledged`) and demotes the doc. `<rel>` is the repo-relative doc path. Public-repo gated (`--confirm=<token>`); `--clear` removes it. |
 | `plan-baseline --repo=<key> [--clear] [--confirm=<token>] -- <rel>` | Stamp the **current computed verdict** into ONE plan/spec doc's YAML **frontmatter only** (`verdict_baseline`) as a drift tripwire. `plan-status` then flags **drift** (emits `verdict_drift`) when the live verdict later diverges from the baseline — catching a once-shipped plan that silently **regressed** (its declared files were deleted/moved), the third "started, then drifted off" signal beyond stalled + lie-gap. The value is computed authoritatively (not taken from the caller); a human `verdict_override` suppresses drift. Public-repo gated; `--clear` removes it. |
 | `close-issue --repo=<key\|slug> [--reason=completed\|not_planned] [--comment=<text>] -- <number>` | ⚠️ A GitHub-mutating command — closes a GitHub issue via `gh issue close`. 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 explicitly. `--reason` maps to GitHub's completed/not-planned; `--comment` posts a closing note. The VS Code viewer gates this behind a mandatory "Close on GitHub? — cannot be undone" modal. |

package/VERSION

@@ -1 +1 @@
-2026.06.24+b047035
+2026.07.03+7d98e1e

package/bin/work-plan

@@ -34,6 +34,14 @@ _wp_missing=""
 _wp_have python3 || _wp_missing="$_wp_missing python3"
 case "${1:-}" in
   --version|-v|--help|-h|"") ;;
+  auth-status)
+    # The VS Code extension's activation probe. It shells out to `gh` only,
+    # never yq. Gating it behind yq means a missing yq makes the probe exit 1
+    # with empty stdout, which the extension can't tell apart from "not logged
+    # in" — so it shows "Not signed in to GitHub" and traps the user in a
+    # sign-in loop that can never satisfy a yq dependency. Require gh alone.
+    _wp_have gh || _wp_missing="$_wp_missing gh"
+    ;;
   *)
     _wp_have yq || _wp_missing="$_wp_missing yq"
     _wp_have gh || _wp_missing="$_wp_missing gh"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.24",
+  "version": "2026.7.3",
   "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"

package/skills/work-plan/SKILL.md

@@ -18,6 +18,9 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Three steps in sequence: ① `refresh-md --all` — pull live GitHub state into every active track's status table (same as "Sync Issue States from GitHub" but for all tracks); ② `reconcile --all` — sync track frontmatter membership against GitHub labels; ③ `duplicates` — flag likely-duplicate issues for consolidation. Run once a week to keep status icons, labels, and dedup state honest. `--repo=<key>` scopes steps ① and ② to one repo; step ③ is skipped in scoped mode (it needs a single explicit repo to be unambiguous). |
 | `/work-plan slot <issue-num> [track]` | A new GitHub issue should belong to a track. If the issue is already listed in another active track's frontmatter, you'll be prompted to move it (remove from source) instead of duplicating. |
 | `/work-plan close [track]` | Track is done (shipped) / paused (parked) / won't ship (abandoned). |
+| `/work-plan mark-cleanup <track> [--reason=<text>] [--clear]` | Earmark a track for cleanup — a reversible `cleanup_candidate` flag `hygiene` surfaces. Triggers: "mark this track for cleanup / retirement". Non-destructive. |
+| `/work-plan archive-track <track>` / `unarchive-track <track>` | **Set a track aside reversibly** into `archive/parked/` (out of active views, kept), or restore it. Distinct from `close` (terminal). Triggers: "archive / park / set aside this track", "bring back that archived track". |
+| `/work-plan delete-track <track>` | **DESTRUCTIVE** — remove a track's `.md`. **Never touches GitHub issues** (they outlive the track). Private: undoable notes-vcs commit; shared: staged `git rm`. Triggers: "delete / remove this track for good". Prefer archive-track if reversible is fine. |
 | `/work-plan refresh-md <track> \| --all \| --repo=<key>` | **Pull live GitHub state into a track's status table.** Run this after closing or merging issues — it re-fetches each issue's open/closed state from GitHub and rewrites the status cells in the track body, which refreshes the dependency graph and `next_up` display. `--all` sweeps every active track; `--repo=<key>` scopes to one repo. In VS Code: right-click a track → **Sync Issue States from GitHub**. |
 | `/work-plan list [--all]` | List active tracks (or all including parked/archived). |
 | `/work-plan init <path>` | Add frontmatter to a new track .md file. |
@@ -31,6 +34,7 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan plan-status [--repo=<key>] [--stamp [--draft]] [--type=plan\|spec]` | **Doc/plan liveness.** "Which of my plan/spec docs actually shipped, half-shipped, or died?" Correlates each plan's declared file-manifest (Create/Modify/Test paths) against git + filesystem — not the unreliable checkboxes. Reports ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less. Read-only by default; `--stamp` writes an idempotent status header into each doc (`--draft` previews, writes nothing). Natural-language triggers: "what's done vs unfinished in `<repo>`", "stamp the plan statuses", "which plans are stale/dead". |
 | `/work-plan plan-confirm --repo=<key> --verdict=shipped\|partial\|dead [--clear] -- <rel>` | **Affirm a human verdict** on one plan doc by writing `verdict_override` into its **frontmatter only** (never body/checkboxes/manifest). `plan-status` then pins that verdict and silences the "shipped but boxes unchecked" lie-gap. Use when a genuinely-shipped plan is flagged red only because nobody ticked its phase checkboxes — confirm it instead of hand-ticking boxes. Public-repo gated (prints `needs_confirm` + token; re-run with `--confirm=<token>`). Natural-language triggers: "that plan really did ship, stop flagging it", "mark `<plan>` as shipped/dead". |
 | `/work-plan plan-archive --repo=<key> [--draft] -- <rel>` | **Archive a shipped plan.** Moves a doc whose effective verdict is shipped into `archive/shipped/` — a staged `git mv` for a tracked doc (commit & push to share), or a plain filesystem move for a gitignored/untracked one (#399). Refuses non-shipped; skips collisions. Natural-language triggers: "archive this finished plan", "file away the shipped plans". Bulk: `plan-status --archive-shipped`. |
+| `/work-plan plan-unarchive --repo=<key> -- <rel>` | **Restore an archived plan** back to the live set — the inverse of `plan-archive` (#388). Moves a doc out of `archive/<kind>/`; refuses a collision with a live doc. Triggers: "un-archive / restore this plan", "I archived that plan by mistake". In VS Code: right-click a doc in the 📦 Archived folder → **Restore to Live**. |
 | `/work-plan plan-ack --repo=<key> [--clear] -- <rel>` | **Durably acknowledge** one plan doc by writing `acknowledged: true` into its **frontmatter only** — a "stop flagging this" that's committed + shared (vs the viewer's per-machine ack). `plan-status` reads it back and demotes the doc. Public-repo gated. Natural-language triggers: "stop flagging this plan for everyone", "acknowledge `<plan>` for good". |
 | `/work-plan plan-baseline --repo=<key> [--clear] -- <rel>` | **Stamp a drift baseline** on one plan doc by writing its current computed verdict to `verdict_baseline` in **frontmatter only**. `plan-status` then flags **drift** when the live verdict diverges — catching a once-shipped plan that silently regressed (files deleted/moved). Distinct from `plan-confirm` (human pin); an override suppresses drift. Public-repo gated. Natural-language triggers: "watch this plan for regressions", "alert me if `<plan>` stops being shipped". |
 

package/skills/work-plan/commands/archive_track.py

@@ -0,0 +1,67 @@
+"""archive-track — set a track aside (reversibly) by moving its .md into
+archive/parked/. Distinct from `close` (terminal shipped/parked/abandoned): an
+archived track is out of the active rotation but kept, and `unarchive-track`
+restores it. Reuses the #399 git-aware move: a shared (git-tracked) track
+archives as a staged `git mv`, a private one as a filesystem move — honest
+messaging either way. Never touches GitHub.
+"""
+import json
+from lib.config import load_config, ConfigError
+from lib.tracks import (discover_tracks, find_track_by_name, parse_track_repo_arg,
+                        AmbiguousTrackError)
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+from lib.archive import move_to_archive
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--confirm", "--repo"})
+    if not positional:
+        print("usage: work_plan.py archive-track <track | track@repo> [--repo=<key>] [--confirm=<token>]")
+        return 2
+
+    name_from_arg, repo_from_arg = parse_track_repo_arg(positional[0])
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+    try:
+        track = find_track_by_name(name_from_arg, discover_tracks(cfg), repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching {name_from_arg!r}.")
+        return 1
+
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+            isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)):
+        print(json.dumps({"needs_confirm": True,
+                          "reason": f"{track.repo} is PUBLIC (or visibility unknown); archiving '{track.name}' will be written there.",
+                          "token": make_token(track.repo, track.name)}))
+        return 0
+
+    # Archive within the track's own directory: base = the doc's dir, rel = its
+    # name. `git -C <base>` resolves the enclosing repo, so is_tracked/git_mv work
+    # whether the tier root is notes_root (private) or a repo clone (shared).
+    base = track.path.parent
+    outcome = move_to_archive(track.path.name, base, "parked")
+    if outcome is None:
+        print(f"ERROR: could not archive {track.name!r} (move failed).")
+        return 1
+    if outcome == "skipped_collision":
+        print(f"Not archived — a file already exists at archive/parked/{track.path.name}.")
+        return 0
+    if outcome == "archived":
+        print(f"✓ '{track.name}' archived → archive/parked/ (staged rename)")
+        if getattr(track, "tier", None) == "shared":
+            print("  ↑ shared track — commit & push to share this archive with teammates.")
+    else:  # archived_local
+        print(f"✓ '{track.name}' archived → archive/parked/ (moved on disk; not git-tracked)")
+    print("  Restore with:  work-plan unarchive-track " + track.name)
+    return 0

package/skills/work-plan/commands/delete_track.py

@@ -0,0 +1,92 @@
+"""delete-track — remove a track's markdown file. DESTRUCTIVE but bounded:
+
+  * It removes ONLY the track's local .md. It NEVER touches GitHub — the issues
+    the track referenced outlive it (deleting a track must not close or delete
+    any issue). This module deliberately imports nothing that mutates GitHub.
+  * Private tier (notes_root, an owned no-remote git root): the deletion is
+    staged via `git rm`, and the dispatcher's notes-vcs auto-commit turns it into
+    an undoable commit.
+  * Shared tier (a repo clone with a remote): the deletion is staged via
+    `git rm` and left for the user to commit & push — recoverable from git
+    history until they do.
+  * An untracked track file: a plain filesystem unlink.
+
+Public/shared repos require the --confirm token (the VS Code modal supplies it,
+plus a stronger type-to-confirm on shared-tier deletes).
+"""
+import json
+from lib.config import load_config, ConfigError
+from lib.tracks import (discover_tracks, discover_archived_tracks,
+                        find_track_by_name, parse_track_repo_arg, AmbiguousTrackError)
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+from lib import git_state
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--confirm", "--repo"})
+    if not positional:
+        print("usage: work_plan.py delete-track <track | track@repo> [--repo=<key>] [--confirm=<token>]")
+        return 2
+
+    name_from_arg, repo_from_arg = parse_track_repo_arg(positional[0])
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    # A track may be deleted whether active or archived — search both tiers.
+    candidates = discover_tracks(cfg) + discover_archived_tracks(cfg)
+    try:
+        track = find_track_by_name(name_from_arg, candidates, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching {name_from_arg!r}.")
+        return 1
+
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+            isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)):
+        print(json.dumps({"needs_confirm": True,
+                          "reason": f"{track.repo} is PUBLIC (or visibility unknown); deleting '{track.name}' will remove its file there.",
+                          "token": make_token(track.repo, track.name)}))
+        return 0
+
+    base = track.path.parent
+    rel = track.path.name
+    # `staged` records whether the deletion went through git (recoverable) or a
+    # bare filesystem unlink (PERMANENT). Recoverability messaging keys on THIS,
+    # not on tier — a private track is only recoverable when notes_root is under
+    # version control (notes-vcs, which is opt-in and OFF by default).
+    if git_state.is_tracked(rel, base):
+        if not git_state.git_rm(rel, base):
+            print(f"ERROR: could not delete {track.name!r} (git rm failed — "
+                  "commit or discard any unsaved edits to it first).")
+            return 1
+        staged = True
+    else:
+        try:
+            track.path.unlink()
+        except OSError as e:
+            print(f"ERROR: could not delete {track.name!r} ({e}).")
+            return 1
+        staged = False
+
+    print(f"✓ deleted track {track.name!r} ({rel})")
+    print("  GitHub issues are untouched — only the track's local .md was removed.")
+    if not staged:
+        print("  ⚠ PERMANENT — this file isn't under version control (notes-vcs is "
+              "off), so the deletion CANNOT be undone. Enable it with "
+              "`work-plan notes-vcs init` for undoable deletes going forward.")
+    elif getattr(track, "tier", None) == "shared":
+        print("  ↑ shared track — the deletion is staged; commit & push to remove it "
+              "for teammates (recoverable from git history until you do).")
+    else:
+        print("  Recoverable via notes-vcs undo (the deletion is an undoable commit).")
+    return 0

package/skills/work-plan/commands/export.py

@@ -2,7 +2,7 @@
 import json
 from datetime import datetime, date
 from lib.config import load_config, ConfigError, resolve_local_path_for_folder
-from lib.tracks import discover_tracks, find_tier_duplicates, issue_refs
+from lib.tracks import discover_tracks, discover_archived_tracks, find_tier_duplicates, issue_refs
 from lib.github_state import fetch_export_issues, fetch_open_issues, repo_visibility
 from lib.git_state import hot_issue_numbers
 from lib.export_model import build_export
@@ -48,15 +48,24 @@ def _plan_badge(track, cfg, today, dead_days, stall_days):
     }
 
 def run(args: list[str]) -> int:
-    flags, _ = parse_flags(args, {"--json"})
+    flags, _ = parse_flags(args, {"--json", "--include-archived"})
     if not flags.get("--json"):
-        print("usage: work-plan export --json"); return 2
+        print("usage: work-plan export --json [--include-archived]"); return 2
     try:
         cfg = load_config()
     except ConfigError as e:
         print(json.dumps({"error": str(e)})); return 1
     tracks = [t for t in discover_tracks(cfg) if t.has_frontmatter]
 
+    # --include-archived (#328): append archived-tier tracks, tagged so the
+    # viewer can render them greyed under a "Show archived" toggle. In-memory
+    # meta flag only (never written back). Excluded by default.
+    if flags.get("--include-archived"):
+        for t in discover_archived_tracks(cfg):
+            if t.has_frontmatter:
+                t.meta["archived"] = True
+                tracks.append(t)
+
     # Build repo_to_numbers: {repo: [number, ...]} deduped per repo, first-seen order.
     repo_to_numbers: dict[str, list[int]] = {}
     for t in tracks:

package/skills/work-plan/commands/hygiene.py

@@ -25,9 +25,30 @@ Pass --timeout=N to set the gh subprocess timeout for the duplicates step
 from commands import refresh_md, reconcile, duplicates, dedupe_tiers
 from lib.config import load_config, ConfigError
 from lib.prompts import parse_flags
+from lib.render import render_cleanup_callout
+from lib.tracks import discover_tracks
 import time
 
 
+def _print_cleanup_callout() -> None:
+    """Print the "marked for cleanup" section if any active track is earmarked
+    via `mark-cleanup` (#328). Best-effort: a config/discovery failure is
+    swallowed so it never derails the hygiene run."""
+    try:
+        cfg = load_config()
+        candidates = [
+            (t.name, t.meta.get("cleanup_reason"))
+            for t in discover_tracks(cfg)
+            if t.meta.get("cleanup_candidate")
+        ]
+    except Exception:
+        return
+    block = render_cleanup_callout(candidates)
+    if block:
+        print()
+        print(block)
+
+
 def _resolve_repo_folder(repo_key: str, cfg: dict):
     """Translate hygiene's --repo arg (folder key OR org/repo slug) to a config
     folder key, which is what duplicates expects. Returns None if unresolvable.
@@ -100,6 +121,12 @@ def run(args: list[str]) -> int:
         print(f"\n⚠ dedupe-tiers exited with code {rc}; continuing.")
     print(f"  (step 3/4 done in {time.time() - t_dt:.1f}s)")
 
+    # Cleanup earmarks (#328): surface tracks flagged via `mark-cleanup` so they
+    # don't get forgotten. Printed after the maintenance steps and before the
+    # (optional) duplicates scan, so it always shows regardless of the --repo /
+    # multi-repo early returns below.
+    _print_cleanup_callout()
+
     if skip_dups:
         print()
         print("(skipping duplicates per --no-duplicates)")

package/skills/work-plan/commands/mark_cleanup.py

@@ -0,0 +1,78 @@
+"""mark-cleanup subcommand — flag (or unflag) a track as a cleanup candidate.
+
+Writes a lightweight `cleanup_candidate: true` marker (plus an optional
+`cleanup_reason`) into a track's frontmatter, so hygiene can surface tracks the
+user has earmarked for retirement/consolidation. `--clear` removes both keys.
+
+Same guarded-write shape as `set`: a PUBLIC-repo track requires a --confirm
+token round-trip; private-tier tracks write straight through. The notes_root
+auto-commit (opt-in local VCS) is handled centrally by the dispatcher.
+
+Usage:
+  mark-cleanup <track | track@repo> [--repo=<key>] [--clear]
+               [--reason=<text>] [--confirm=<token>]
+"""
+import json
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--repo", "--clear", "--reason", "--confirm"})
+    if len(positional) < 1:
+        print("usage: work_plan.py mark-cleanup <track | track@repo> [--repo=<key>] "
+              "[--clear] [--reason=<text>] [--confirm=<token>]")
+        return 2
+
+    track_arg = positional[0]
+    name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+    name = name_from_arg
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+
+    clear = flags.get("--clear", False)
+    reason = flags.get("--reason")
+    reason = reason if isinstance(reason, str) else None
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    try:
+        track = find_track_by_name(name, discover_tracks(cfg), repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching {name!r}.")
+        return 1
+
+    # Public-repo confirm gate (the extension surfaces this as a modal).
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)):
+        print(json.dumps({"needs_confirm": True,
+                          "reason": f"{track.repo} is PUBLIC (or visibility unknown); edit will be written there.",
+                          "token": make_token(track.repo, track.name)}))
+        return 0
+
+    if clear:
+        track.meta.pop("cleanup_candidate", None)
+        track.meta.pop("cleanup_reason", None)
+        write_file(track.path, track.meta, track.body)
+        print(f"✓ cleared cleanup mark on {track.name!r}")
+        return 0
+
+    track.meta["cleanup_candidate"] = True
+    if reason:
+        track.meta["cleanup_reason"] = reason
+    write_file(track.path, track.meta, track.body)
+    if reason:
+        print(f"✓ {track.name!r} marked for cleanup — {reason}")
+    else:
+        print(f"✓ {track.name!r} marked for cleanup")
+    return 0

package/skills/work-plan/commands/plan_unarchive.py

@@ -0,0 +1,87 @@
+"""plan-unarchive — restore ONE archived plan/spec doc back out of
+`archive/<kind>/` to its live location (#388). The inverse of plan-archive;
+reuses the git-aware `restore_from_archive` primitive. A name collision with a
+live doc is refused, never overwritten.
+
+Interactivity mirrors plan-archive: behind a y/N prompt by default, `--yes` for
+non-interactive callers (the VS Code viewer), `--json` for a single parseable
+outcome object.
+
+Usage:
+    work_plan.py plan-unarchive --repo=<key> [--draft] [--yes] [--json] -- <rel>
+"""
+import json
+import sys
+from pathlib import Path, PurePosixPath
+
+from commands import plan_status
+from lib import archive as archive_lib
+from lib.prompts import parse_flags, prompt_yes_no
+
+KNOWN = {"--repo", "--draft", "--yes", "--json"}
+
+
+def _restore_dest(rel: str):
+    """The live path an archived `rel` restores to (strip archive/<kind>/), or
+    None when `rel` isn't under archive/<kind>/."""
+    p = PurePosixPath(rel)
+    if p.parent.parent.name != "archive":
+        return None
+    return str(p.parent.parent.parent / p.name)
+
+
+def _emit(as_json: bool, rel: str, outcome: str, dest, human: str) -> None:
+    if as_json:
+        print(json.dumps({"action": "unarchive", "rel": rel,
+                          "outcome": outcome, "dest": dest}))
+    else:
+        print(human)
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+    if not flags.get("--repo") or flags.get("--repo") is True:
+        print("ERROR: --repo=<key> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py plan-unarchive --repo=<key> [--draft] [--yes] "
+              "[--json] -- <rel>", file=sys.stderr)
+        return 2
+    rel = positional[0]
+    as_json = bool(flags.get("--json"))
+    repo_root = plan_status._resolve_repo_root(flags)
+
+    dest = _restore_dest(rel)
+    if dest is None:
+        print(f"ERROR: '{rel}' is not under archive/<kind>/ — nothing to restore.",
+              file=sys.stderr)
+        return 1
+    if not (Path(repo_root) / rel).is_file():
+        print(f"ERROR: archived doc '{rel}' not found under {repo_root}",
+              file=sys.stderr)
+        return 1
+
+    if flags.get("--draft"):
+        print(f"Would restore  {rel}  ->  {dest}")
+        return 0
+
+    if not flags.get("--yes"):
+        if not prompt_yes_no(f"Restore {rel} -> {dest}? [y/N]"):
+            print("Skipped.")
+            return 0
+
+    outcome = archive_lib.restore_from_archive(rel, repo_root)
+    if outcome is None:
+        print(f"ERROR: restore failed for {rel}", file=sys.stderr)
+        return 1
+    if outcome == "skipped_collision":
+        _emit(as_json, rel, "skipped_collision", dest,
+              f"a live doc already exists at {dest} — skipped")
+        return 0
+    if outcome == "restored_local":
+        _emit(as_json, rel, "restored_local", dest,
+              f"✓ restored {rel} -> {dest} (moved on disk; not git-tracked)")
+        return 0
+    _emit(as_json, rel, "restored", dest,
+          f"✓ restored {rel} -> {dest} (staged rename — commit & push to share)")
+    return 0

package/skills/work-plan/commands/unarchive_track.py

@@ -0,0 +1,64 @@
+"""unarchive-track — restore an archived track (parked / shipped / abandoned)
+back into the active set. The inverse of archive-track (and of `close`'s move).
+Reuses the #399 git-aware restore primitive. Never touches GitHub.
+"""
+import json
+from lib.config import load_config, ConfigError
+from lib.tracks import (discover_archived_tracks, find_track_by_name,
+                        parse_track_repo_arg, AmbiguousTrackError)
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+from lib.archive import restore_from_archive
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--confirm", "--repo"})
+    if not positional:
+        print("usage: work_plan.py unarchive-track <track | track@repo> [--repo=<key>] [--confirm=<token>]")
+        return 2
+
+    name_from_arg, repo_from_arg = parse_track_repo_arg(positional[0])
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+    try:
+        track = find_track_by_name(name_from_arg, discover_archived_tracks(cfg), repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No archived track matching {name_from_arg!r}.")
+        return 1
+
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+            isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)):
+        print(json.dumps({"needs_confirm": True,
+                          "reason": f"{track.repo} is PUBLIC (or visibility unknown); restoring '{track.name}' will be written there.",
+                          "token": make_token(track.repo, track.name)}))
+        return 0
+
+    # The archived path is `.../<kind-parent>/archive/<kind>/<name>`. Restore
+    # relative to the directory ABOVE the `archive/` segment so the doc lands
+    # back where it started. base = 3 levels up (strip archive/<kind>/<name>).
+    base = track.path.parent.parent.parent
+    rel = track.path.relative_to(base).as_posix()
+    outcome = restore_from_archive(rel, base)
+    if outcome is None:
+        print(f"ERROR: could not restore {track.name!r} (not under archive/<kind>/, or move failed).")
+        return 1
+    if outcome == "skipped_collision":
+        print(f"Not restored — an active track already exists at {track.path.name}.")
+        return 0
+    if outcome == "restored":
+        print(f"✓ '{track.name}' restored to the active set (staged rename)")
+        if getattr(track, "tier", None) == "shared":
+            print("  ↑ shared track — commit & push to share the restore with teammates.")
+    else:  # restored_local
+        print(f"✓ '{track.name}' restored to the active set (moved on disk; not git-tracked)")
+    return 0

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

@@ -4,7 +4,7 @@ archive/<kind>/. For tracked files the move is a history-preserving `git mv`
 filesystem move. Eligibility (is-this-shipped) is the caller's job — this
 only moves files."""
 import shutil
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 
 from lib import git_state
 from lib import reconcile_actions
@@ -34,3 +34,34 @@ def move_to_archive(rel: str, repo_root, kind: str):
         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

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