@stylusnexus/work-plan 2026.6.22 → 2026.7.3

package/README.md

@@ -314,6 +314,8 @@ Install it from either registry:
 
 The extension **shells out to the `work-plan` CLI**, so install the CLI too (npm or any method above). If `work-plan` isn't on your editor's `PATH` — common when VS Code is launched from the Dock/Finder rather than a terminal — set **`workPlan.cliPath`** in Settings to an absolute launcher path (e.g. `/path/to/work-plan-toolkit/bin/work-plan`, or the npm global bin), then reload the window. Extensions auto-update from the registry.
 
+> **Windows + WSL (and Remote-SSH / dev containers): install the CLI where the extension *runs*, not where you clicked.** When you open a folder in WSL — e.g. `code .` from a WSL shell, or **Reopen in WSL** (the window shows **`WSL: <distro>`** at the bottom-left) — VS Code runs the extension *inside WSL*, so it looks for `work-plan`, `gh`, `python3`, and `yq` on the **WSL** `PATH`. A CLI installed on **Windows-native** is invisible to it, and you'll see a **"work-plan CLI not found"** banner (or, on older builds, a misleading "Not signed in to GitHub" one) even though `gh` is signed in. Fix: open the **WSL** terminal and run `npm install -g @stylusnexus/work-plan` (plus `gh`, `python3`, `yq`) there, then **reload the window**. The same rule applies to Remote-SSH and dev containers — the CLI must live in the remote, not on your local machine. (`gh auth` is likewise per-environment: `gh auth login` inside WSL authenticates the WSL `gh`, which is what the extension reads.)
+
 Useful settings:
 
 | Setting | Default | What it does |
@@ -527,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. |
@@ -541,7 +547,8 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `canonicalize <track>` | Add a canonical issue table to a track file (so `refresh-md` knows where to update). The table carries a `Milestone` column and is ordered active-milestone-first — issues in the track's `milestone_alignment` milestone, then other milestones grouped (blank divider row between groups), then no-milestone last — so "what's next" sits above "someday" (#101). It's one table (not per-milestone sub-tables) so `refresh-md` re-derives it cleanly. |
 | `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. |
+| `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.22+f62c4cc
+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.22",
+  "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. |
@@ -30,7 +33,8 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan duplicates [--min-similarity=0.7]` | Find likely-duplicate issues by title similarity (stdlib difflib). |
 | `/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/` (`git mv`). 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-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_archive.py

@@ -76,11 +76,16 @@ def run(args: list) -> int:
 
     outcome = archive_lib.move_to_archive(rel, repo_root, "shipped")
     if outcome is None:
-        print(f"ERROR: git mv failed for {rel}", file=sys.stderr)
+        print(f"ERROR: archive move failed for {rel}", file=sys.stderr)
         return 1
     if outcome == "skipped_collision":
         _emit(as_json, rel, "skipped_collision", dest,
               f"destination already exists: {dest} — skipped")
         return 0
-    _emit(as_json, rel, "archived", dest, f"✓ archived {rel} -> {dest}")
+    if outcome == "archived_local":
+        _emit(as_json, rel, "archived_local", dest,
+              f"✓ archived {rel} -> {dest} (moved on disk; not git-tracked)")
+        return 0
+    _emit(as_json, rel, "archived", dest,
+          f"✓ archived {rel} -> {dest} (staged rename — commit & push to share)")
     return 0

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

@@ -356,11 +356,14 @@ def _archive_dead(docs, rows, repo_root, draft: bool) -> int:
     moved = 0
     for r in dead:
         dest = reconcile_actions.archive_dest(r["rel"])
-        if git_state.git_mv(r["rel"], dest, repo_root):
+        outcome = archive_lib.move_to_archive(r["rel"], repo_root, "abandoned")
+        if outcome in ("archived", "archived_local"):
             moved += 1
-            print(f"  ✓ {r['rel']}")
+            suffix = " (moved on disk; not git-tracked)" if outcome == "archived_local" else ""
+            print(f"  ✓ {r['rel']}{suffix}")
         else:
-            print(f"  ✗ {r['rel']} (git mv failed)")
+            reason = "already exists at destination" if outcome == "skipped_collision" else "move failed"
+            print(f"  ✗ {r['rel']} ({reason})")
     print(f"Archived {moved}/{len(dead)}.")
     return 0
 
@@ -379,8 +382,9 @@ def _archive_shipped(rows, repo_root, draft, as_json, include_lie_gap, yes=False
             for r in targets:
                 outcome = archive_lib.move_to_archive(r["rel"], repo_root, "shipped")
                 dest = reconcile_actions.archive_dest(r["rel"], "shipped")
-                if outcome == "archived":
-                    archived.append({"rel": r["rel"], "dest": dest})
+                if outcome in ("archived", "archived_local"):
+                    archived.append({"rel": r["rel"], "dest": dest,
+                                     "outcome": outcome})
                 elif outcome == "skipped_collision":
                     skipped.append({"rel": r["rel"], "reason": "collision"})
         print(json.dumps({
@@ -413,10 +417,13 @@ def _archive_shipped(rows, repo_root, draft, as_json, include_lie_gap, yes=False
         outcome = archive_lib.move_to_archive(r["rel"], repo_root, "shipped")
         if outcome == "archived":
             archived += 1
-            print(f"  ✓ {r['rel']}")
+            print(f"  ✓ {r['rel']} (staged rename — commit & push to share)")
+        elif outcome == "archived_local":
+            archived += 1
+            print(f"  ✓ {r['rel']} (moved on disk; not git-tracked)")
         else:
             skipped += 1
-            print(f"  ✗ {r['rel']} ({outcome or 'git mv failed'})")
+            print(f"  ✗ {r['rel']} ({outcome or 'move failed'})")
     print(f"Archived {archived}, skipped {skipped}.")
     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