@stylusnexus/work-plan 2026.6.19 → 2026.6.21

package/README.md

@@ -537,8 +537,9 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft] [--yes]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). In an `--all`/`--repo` sweep it also detects **MOVEs** — an issue relabeled from one track to another in the same repo is moved (removed from the old track, added to the new); ambiguous targets stay as FLAGs. `--draft` previews the label drift (ADDs/MOVEs/FLAGs) without prompting or writing. `--yes` applies without prompting (non-interactive, e.g. the VS Code extension); PUBLIC-repo move destinations are skipped under `--yes`. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
 | `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. |
+| `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-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. |
@@ -564,6 +565,8 @@ Every write verb the VS Code extension drives runs **without a TTY** — explici
 
 **The Plans view can write to plan-doc frontmatter — and only frontmatter.** Right-click a plan in the viewer → **Confirm Verdict…** / **Clear Confirmation** (writes `verdict_override`), **Acknowledge & Save to Doc** / **Clear Saved Acknowledgment** (writes `acknowledged`), or **Stamp Baseline — Watch for Drift** / **Clear Baseline** (writes `verdict_baseline`) drives the matching CLI write behind a mandatory modal that names the exact file and states the write touches only the doc's YAML frontmatter — never its prose body, checkboxes, or declared-file manifest. These are the only viewer-initiated writes to a plan doc, each touches one frontmatter key and nothing else, and on a public repo each additionally passes through the public-repo confirm modal above. The default **Acknowledge (stop flagging)** remains per-machine and writes nothing to git; **Acknowledge & Save to Doc** is the opt-in durable, shared variant. Everything else the Plans view does (scan, local acknowledge) remains read-only on git.
 
+Archived shipped plans (`plan-archive` / `plan-status --archive-shipped`) move into `archive/shipped/` and drop out of the live verdict buckets; the viewer surfaces them in a collapsed **"Archived (N)"** node per repo. Right-click a shipped plan → **Archive Plan…**, or a repo → **Archive shipped plans…**.
+
 ## Version
 
 ```bash

package/VERSION

@@ -1 +1 @@
-2026.06.19+9cf7cdc
+2026.06.21+4cab67a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.19",
+  "version": "2026.6.21",
   "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

@@ -30,6 +30,7 @@ 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-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/plan_archive.py

@@ -0,0 +1,86 @@
+"""plan-archive — move ONE plan/spec doc whose effective verdict is `shipped`
+into archive/shipped/ (history-preserving git mv).
+
+Eligibility uses the same `_evaluate` machinery as plan-status, so an
+override-confirmed or lie-gap shipped doc qualifies (its effective verdict is
+shipped). Non-shipped docs are refused (no move). A name collision in the
+archive dir is skipped, never overwritten.
+
+Interactivity: behind a y/N prompt by default (terminal use). `--yes` skips the
+prompt for non-interactive callers (the VS Code viewer) — required because
+lib/prompts.py defaults to "no" on non-TTY stdin. `--json` emits a single
+JSON-only object (no prompts/human lines) so the viewer can parse the outcome.
+
+Usage:
+    work_plan.py plan-archive --repo=<key> [--draft] [--yes] [--json] -- <rel>
+"""
+import json
+import sys
+from datetime import date
+
+from commands import plan_status
+from lib import archive as archive_lib
+from lib import doc_discovery, reconcile_actions, verdict as verdict_mod
+from lib.prompts import parse_flags, prompt_yes_no
+
+KNOWN = {"--repo", "--draft", "--yes", "--json"}
+
+
+def _emit(as_json: bool, rel: str, outcome: str, dest, human: str) -> None:
+    if as_json:
+        print(json.dumps({"action": "archive", "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-archive --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)
+    docs = doc_discovery.discover_docs(repo_root)
+    doc = next((d for d in docs if d.rel == rel), None)
+    if doc is None:
+        print(f"ERROR: '{rel}' is not a discovered plan doc inside {repo_root}",
+              file=sys.stderr)
+        return 1
+
+    today = date.today()
+    stall_days = plan_status._resolve_stall_days(flags)
+    row = plan_status._evaluate(doc, repo_root, today, verdict_mod.DEAD_DAYS, stall_days)
+
+    dest = reconcile_actions.archive_dest(rel, "shipped")
+    if row["verdict"] != "shipped":
+        _emit(as_json, rel, "refused_not_shipped", None,
+              f"✗ {rel} is '{row['verdict']}', not shipped — not archived.")
+        return 0
+
+    if flags.get("--draft"):
+        # Human preview only; the viewer never combines --draft with --json.
+        print(f"Would archive  {rel}  ->  {dest}")
+        return 0
+
+    if not flags.get("--yes"):
+        if not prompt_yes_no(f"Archive {rel} -> {dest}? [y/N]"):
+            print("Skipped.")
+            return 0
+
+    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)
+        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}")
+    return 0

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

@@ -16,11 +16,13 @@ from lib import verdict as verdict_mod
 from lib import status_header
 from lib import llm_evidence
 from lib import reconcile_actions
+from lib import archive as archive_lib
 from lib.scratch import cache_dir
 from lib.prompts import parse_flags, prompt_yes_no
 
 KNOWN = {"--repo", "--json", "--since-days", "--type", "--stamp", "--draft",
-         "--llm", "--apply", "--archive", "--issues", "--stall-days"}
+         "--llm", "--apply", "--archive", "--issues", "--stall-days",
+         "--include-archived", "--archive-shipped", "--include-lie-gap", "--yes"}
 _ORDER = ["shipped", "partial", "dead", "foreign", "manifest-less"]
 
 # Human verdict-override (#286): a reviewer affirms the verdict in the doc's
@@ -166,6 +168,7 @@ def _evaluate(doc, repo_root, today, dead_days, stall_days) -> dict:
     verdict_drift = bool(baseline) and not override and baseline != v.label
     return {
         "rel": doc.rel, "kind": doc.kind,
+        "archived": doc.archived, "archive_kind": doc.archive_kind,
         "verdict": v.label, "glyph": v.glyph, "rationale": v.rationale,
         "files_present": score.satisfied, "files_declared": score.total,
         "checkboxes_done": done, "checkboxes_total": total_chk,
@@ -193,7 +196,7 @@ evaluate_doc = _evaluate
 
 def _render(rows, repo_root) -> None:
     print(f"# plan-status — {repo_root}\n")
-    by = {}
+    by: dict = {}
     for r in rows:
         by.setdefault(r["verdict"], []).append(r)
     lie_gap = sum(1 for r in rows if r["lie_gap"])
@@ -330,6 +333,62 @@ def _archive_dead(docs, rows, repo_root, draft: bool) -> int:
     return 0
 
 
+def _archive_shipped(rows, repo_root, draft, as_json, include_lie_gap, yes=False):
+    """Batch-archive every effective-shipped LIVE doc into archive/shipped/.
+    Lie-gap docs are excluded unless include_lie_gap; collisions are skipped."""
+    live = [r for r in rows if not r.get("archived")]
+    targets = reconcile_actions.shipped_rows(live, include_lie_gap=include_lie_gap)
+    excluded = [r for r in reconcile_actions.shipped_rows(live, include_lie_gap=True)
+                if r.get("lie_gap") and not include_lie_gap]
+
+    if as_json:
+        archived, skipped = [], []
+        if not draft:
+            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})
+                elif outcome == "skipped_collision":
+                    skipped.append({"rel": r["rel"], "reason": "collision"})
+        print(json.dumps({
+            "action": "archive_shipped",
+            "archived": archived,
+            "skipped": skipped,
+            "lie_gap_excluded": [{"rel": r["rel"]} for r in excluded],
+        }))
+        return 0
+
+    if not targets:
+        print("No shipped plans to archive.")
+        if excluded:
+            print(f"({len(excluded)} unverified lie-gap shipped — "
+                  f"pass --include-lie-gap to include.)")
+        return 0
+    print(f"\n{'Would archive' if draft else 'Archive'} {len(targets)} shipped plan(s):")
+    for r in targets:
+        print(f"  {r['rel']}  ->  {reconcile_actions.archive_dest(r['rel'], 'shipped')}")
+    if excluded:
+        print(f"  (excluding {len(excluded)} unverified lie-gap; "
+              f"--include-lie-gap to include)")
+    if draft:
+        return 0
+    if not yes and not prompt_yes_no(f"Move {len(targets)} plan(s) to archive/shipped/? [y/N]"):
+        print("Skipped.")
+        return 0
+    archived = skipped = 0
+    for r in targets:
+        outcome = archive_lib.move_to_archive(r["rel"], repo_root, "shipped")
+        if outcome == "archived":
+            archived += 1
+            print(f"  ✓ {r['rel']}")
+        else:
+            skipped += 1
+            print(f"  ✗ {r['rel']} ({outcome or 'git mv failed'})")
+    print(f"Archived {archived}, skipped {skipped}.")
+    return 0
+
+
 def _repo_slug(flags):
     """Resolve the org/repo GitHub slug for the --repo key (for issue creation)."""
     repo = flags.get("--repo")
@@ -386,7 +445,7 @@ def run(args: list) -> int:
     flags, _ = parse_flags(args, KNOWN)
     repo_root = _resolve_repo_root(flags)
     raw_days = flags.get("--since-days")
-    if raw_days in (None, True):
+    if not isinstance(raw_days, str):
         dead_days = verdict_mod.DEAD_DAYS
     else:
         try:
@@ -396,7 +455,8 @@ def run(args: list) -> int:
             return 2
     today = date.today()
 
-    docs = doc_discovery.discover_docs(repo_root)
+    docs = doc_discovery.discover_docs(
+        repo_root, include_archived=bool(flags.get("--include-archived")))
     type_filter = flags.get("--type")
     if type_filter and type_filter is not True:
         docs = [d for d in docs if d.kind == type_filter]
@@ -414,6 +474,13 @@ def run(args: list) -> int:
     if flags.get("--archive"):
         return _archive_dead(docs, rows, repo_root, draft=bool(flags.get("--draft")))
 
+    if flags.get("--archive-shipped"):
+        return _archive_shipped(rows, repo_root,
+                                draft=bool(flags.get("--draft")),
+                                as_json=bool(flags.get("--json")),
+                                include_lie_gap=bool(flags.get("--include-lie-gap")),
+                                yes=bool(flags.get("--yes")))
+
     if flags.get("--issues"):
         return _issues_for_partials(docs, rows, repo_root, _repo_slug(flags),
                                     draft=bool(flags.get("--draft")))
@@ -421,7 +488,14 @@ def run(args: list) -> int:
     if flags.get("--json"):
         print(json.dumps({"repo": str(repo_root), "docs": rows}, indent=2))
         return 0
-    _render(rows, repo_root)
+    live_rows = [r for r in rows if not r.get("archived")]
+    _render(live_rows, repo_root)
+    n_shipped = len(reconcile_actions.shipped_rows(live_rows, include_lie_gap=True))
+    if n_shipped:
+        print(f"\n{n_shipped} shipped — archive with "
+              f"'plan-archive -- <rel>' or 'plan-status --archive-shipped'.")
     if flags.get("--stamp"):
-        _stamp_docs(docs, rows, draft=bool(flags.get("--draft")))
+        live_docs = [d for d in docs if not d.archived]
+        _stamp_docs(live_docs, [r for r in rows if not r.get("archived")],
+                    draft=bool(flags.get("--draft")))
     return 0

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

@@ -0,0 +1,21 @@
+"""The archive move primitive: collision-checked, history-preserving `git mv`
+of a doc into archive/<kind>/. Eligibility (is-this-shipped) is the caller's
+job — this only moves files."""
+from pathlib import Path
+
+from lib import git_state
+from lib import reconcile_actions
+
+
+def move_to_archive(rel: str, repo_root, kind: str):
+    """git-mv `rel` into archive/<kind>/. Returns:
+      "archived"          on a clean move,
+      "skipped_collision" if the destination already exists (never overwrite),
+      None                if git_mv failed for any other reason (hard error).
+    """
+    dest = reconcile_actions.archive_dest(rel, kind)
+    if (Path(repo_root) / dest).exists():
+        return "skipped_collision"
+    if git_state.git_mv(rel, dest, repo_root):
+        return "archived"
+    return None

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

@@ -9,12 +9,16 @@ DEFAULT_GLOBS = [
     "docs/plans/*.md",
 ]
 
+ARCHIVE_SUBDIRS = [("archive/shipped", "shipped"), ("archive/abandoned", "abandoned")]
+
 
 @dataclass
 class Doc:
     path: Path   # absolute
     rel: str     # repo-relative POSIX-style
     kind: str    # "plan" | "spec" | "adhoc"
+    archived: bool = False
+    archive_kind: Optional[str] = None   # "shipped" | "abandoned" | None
 
 
 def classify_kind(rel: str) -> str:
@@ -26,7 +30,8 @@ def classify_kind(rel: str) -> str:
     return "adhoc"
 
 
-def discover_docs(repo_root: Path, globs: Optional[list] = None) -> list:
+def discover_docs(repo_root: Path, globs: Optional[list] = None,
+                  include_archived: bool = False) -> list:
     globs = globs or DEFAULT_GLOBS
     repo_root = Path(repo_root)
     out = []
@@ -38,4 +43,15 @@ def discover_docs(repo_root: Path, globs: Optional[list] = None) -> list:
             seen.add(p)
             rel = p.relative_to(repo_root).as_posix()
             out.append(Doc(path=p, rel=rel, kind=classify_kind(rel)))
+    if include_archived:
+        for g in globs:
+            parent = g.rsplit("/", 1)[0]            # "docs/plans/*.md" -> "docs/plans"
+            for sub, kind in ARCHIVE_SUBDIRS:
+                for p in sorted(repo_root.glob(f"{parent}/{sub}/*.md")):
+                    if not p.is_file() or p in seen:
+                        continue
+                    seen.add(p)
+                    rel = p.relative_to(repo_root).as_posix()
+                    out.append(Doc(path=p, rel=rel, kind=classify_kind(rel),
+                                   archived=True, archive_kind=kind))
     return out

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

@@ -198,8 +198,8 @@ def _normalize_gql_node(node) -> Optional[dict]:
     deps_truncated."""
     if not node:
         return None
-    labels = [{"name": l.get("name")} for l in
-              ((node.get("labels") or {}).get("nodes") or []) if l.get("name")]
+    labels = [{"name": lbl.get("name")} for lbl in
+              ((node.get("labels") or {}).get("nodes") or []) if lbl.get("name")]
     assignees = [{"login": a.get("login")} for a in
                  ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
     ms = node.get("milestone")
@@ -378,7 +378,7 @@ def fetch_open_issues(repo: str, limit: int = 1000) -> list[dict]:
         return []
 
 
-def fetch_recent_issues(repo: str, since_iso: str, extra_labels: list[str] = None) -> list[dict]:
+def fetch_recent_issues(repo: str, since_iso: str, extra_labels: Optional[list[str]] = None) -> list[dict]:
     """Fetch issues created since `since_iso` (date YYYY-MM-DD)."""
     if not _valid_repo(repo):
         return []
@@ -434,7 +434,7 @@ def repo_visibility(repo: str) -> Optional[str]:
 
 
 def extract_priority(labels: list[dict]) -> str:
-    label_names = {l["name"] for l in labels}
+    label_names = {lbl["name"] for lbl in labels}
     for p in PRIORITY_LABELS:
         if p in label_names:
             return p.split("/")[1]

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

@@ -31,7 +31,7 @@ def strip_range(p: str) -> str:
 
 def parse_declared_paths(text: str) -> list:
     """Extract declared file paths. First kind seen per path wins (dedup)."""
-    seen = {}  # path -> kind
+    seen: dict[str, str] = {}  # path -> kind
     for kind, raw in PATH_RE.findall(text):
         p = strip_range(raw)
         if "/" not in p:                       # skip bare tokens / commands
@@ -141,7 +141,8 @@ def score_manifest(
     offline testing; defaults wire to the filesystem and git.
     """
     if exists is None:
-        exists = lambda rel: (Path(repo_root) / rel).exists()
+        def exists(rel):
+            return (Path(repo_root) / rel).exists()
     if committed_since is None:
         from lib import git_state
         # Deliberate degradation: with no plan date we can't ask "committed since
@@ -181,7 +182,8 @@ def unsatisfied_paths(
     Same satisfaction rule and injectable predicates as `score_manifest`.
     """
     if exists is None:
-        exists = lambda rel: (Path(repo_root) / rel).exists()
+        def exists(rel):
+            return (Path(repo_root) / rel).exists()
     if committed_since is None:
         from lib import git_state
         committed_since = (

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

@@ -12,10 +12,24 @@ def partial_rows(rows: list) -> list:
     return [r for r in rows if r["verdict"] == "partial"]
 
 
-def archive_dest(rel: str) -> str:
-    """docs/.../plans/x.md -> docs/.../plans/archive/abandoned/x.md"""
+def shipped_rows(rows: list, include_lie_gap: bool = False) -> list:
+    """Rows whose EFFECTIVE verdict is shipped. Lie-gap shipped rows are
+    excluded unless include_lie_gap=True (so an unverified plan can't be swept
+    invisibly inside a batch)."""
+    out = []
+    for r in rows:
+        if r["verdict"] != "shipped":
+            continue
+        if r.get("lie_gap") and not include_lie_gap:
+            continue
+        out.append(r)
+    return out
+
+
+def archive_dest(rel: str, kind: str = "abandoned") -> str:
+    """docs/.../plans/x.md -> docs/.../plans/archive/<kind>/x.md"""
     p = PurePosixPath(rel)
-    return str(p.parent / "archive" / "abandoned" / p.name)
+    return str(p.parent / "archive" / kind / p.name)
 
 
 def issue_for(doc, row, unsatisfied) -> tuple:

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

@@ -0,0 +1,90 @@
+"""Pure archive helpers: destination path + shipped-row selection (offline)."""
+import sys
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib import reconcile_actions as ra
+
+
+class ArchiveDestTest(unittest.TestCase):
+    def test_default_kind_is_abandoned(self):
+        self.assertEqual(
+            ra.archive_dest("docs/plans/x.md"),
+            "docs/plans/archive/abandoned/x.md",
+        )
+
+    def test_shipped_kind(self):
+        self.assertEqual(
+            ra.archive_dest("docs/plans/x.md", kind="shipped"),
+            "docs/plans/archive/shipped/x.md",
+        )
+
+    def test_nested_dir_preserved(self):
+        self.assertEqual(
+            ra.archive_dest("docs/superpowers/specs/y-design.md", kind="shipped"),
+            "docs/superpowers/specs/archive/shipped/y-design.md",
+        )
+
+
+class ShippedRowsTest(unittest.TestCase):
+    ROWS = [
+        {"rel": "a.md", "verdict": "shipped", "lie_gap": False},
+        {"rel": "b.md", "verdict": "shipped", "lie_gap": True},   # lie-gap
+        {"rel": "c.md", "verdict": "partial", "lie_gap": False},
+        {"rel": "d.md", "verdict": "dead", "lie_gap": False},
+    ]
+
+    def test_excludes_lie_gap_by_default(self):
+        rels = [r["rel"] for r in ra.shipped_rows(self.ROWS)]
+        self.assertEqual(rels, ["a.md"])
+
+    def test_includes_lie_gap_when_opted_in(self):
+        rels = [r["rel"] for r in ra.shipped_rows(self.ROWS, include_lie_gap=True)]
+        self.assertEqual(rels, ["a.md", "b.md"])
+
+
+import tempfile
+from unittest import mock
+from lib import archive as archive_lib
+
+
+class MoveToArchiveTest(unittest.TestCase):
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/plans").mkdir(parents=True)
+        (root / "docs/plans/x.md").write_text("# x")
+        return root
+
+    def test_archived_calls_git_mv_to_shipped_dir(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("lib.archive.git_state.git_mv", return_value=True) as mv:
+                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertEqual(outcome, "archived")
+            mv.assert_called_once_with(
+                "docs/plans/x.md", "docs/plans/archive/shipped/x.md", root)
+
+    def test_collision_skips_without_calling_git_mv(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            dest = root / "docs/plans/archive/shipped"
+            dest.mkdir(parents=True)
+            (dest / "x.md").write_text("# already here")
+            with mock.patch("lib.archive.git_state.git_mv") as mv:
+                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertEqual(outcome, "skipped_collision")
+            mv.assert_not_called()
+
+    def test_git_mv_failure_returns_none(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("lib.archive.git_state.git_mv", return_value=False):
+                outcome = archive_lib.move_to_archive("docs/plans/x.md", root, "shipped")
+            self.assertIsNone(outcome)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,47 @@
+"""discover_docs include_archived pass: archived docs are excluded by default
+and included + tagged when opted in (offline, filesystem only)."""
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from lib import doc_discovery
+
+
+def _repo(d):
+    root = Path(d)
+    (root / "docs/plans").mkdir(parents=True)
+    (root / "docs/plans/live.md").write_text("# live")
+    (root / "docs/plans/archive/shipped").mkdir(parents=True)
+    (root / "docs/plans/archive/shipped/done.md").write_text("# done")
+    (root / "docs/plans/archive/abandoned").mkdir(parents=True)
+    (root / "docs/plans/archive/abandoned/dead.md").write_text("# dead")
+    return root
+
+
+class DiscoverArchivedTest(unittest.TestCase):
+    def test_default_excludes_archived(self):
+        with tempfile.TemporaryDirectory() as d:
+            docs = doc_discovery.discover_docs(_repo(d))
+            rels = sorted(x.rel for x in docs)
+            self.assertEqual(rels, ["docs/plans/live.md"])
+
+    def test_include_archived_tags_shipped_and_abandoned(self):
+        with tempfile.TemporaryDirectory() as d:
+            docs = doc_discovery.discover_docs(_repo(d), include_archived=True)
+            by_rel = {x.rel: x for x in docs}
+            self.assertIn("docs/plans/archive/shipped/done.md", by_rel)
+            self.assertIn("docs/plans/archive/abandoned/dead.md", by_rel)
+            self.assertTrue(by_rel["docs/plans/archive/shipped/done.md"].archived)
+            self.assertEqual(
+                by_rel["docs/plans/archive/shipped/done.md"].archive_kind, "shipped")
+            self.assertEqual(
+                by_rel["docs/plans/archive/abandoned/dead.md"].archive_kind, "abandoned")
+            self.assertFalse(by_rel["docs/plans/live.md"].archived)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,96 @@
+"""plan-archive: per-doc archive of a shipped plan. Offline — git_mv mocked,
+repo resolution via Path.cwd patch (no config file)."""
+import io
+import json
+import sys
+import tempfile
+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_archive
+
+SHIPPED_BODY = "# P\n\n**Files:**\n- Create: `src/new.ts`\n- [x] Step 1\n"
+PARTIAL_BODY = "# P\n\n**Files:**\n- Create: `src/missing.ts`\n- [ ] Step 1\n"
+
+
+def _repo(d, body, present=True):
+    root = Path(d)
+    (root / "docs/plans").mkdir(parents=True)
+    (root / "docs/plans/p.md").write_text(body)
+    if present:
+        (root / "src").mkdir()
+        (root / "src/new.ts").write_text("export const x = 1")
+    return root
+
+
+def _run(root, args):
+    with mock.patch("commands.plan_archive.plan_status.git_state.path_last_commit_date",
+                    return_value=None), \
+         mock.patch("commands.plan_archive.plan_status._resolve_repo_root",
+                    return_value=root):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = plan_archive.run(args)
+    return rc, buf.getvalue()
+
+
+class PlanArchiveTest(unittest.TestCase):
+    def test_archives_shipped_with_yes_json(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo(d, SHIPPED_BODY)
+            with mock.patch("commands.plan_archive.archive_lib.git_state.git_mv",
+                            return_value=True) as mv:
+                rc, out = _run(root, ["--repo=x", "--yes", "--json",
+                                      "--", "docs/plans/p.md"])
+            self.assertEqual(rc, 0)
+            payload = json.loads(out)
+            self.assertEqual(payload["outcome"], "archived")
+            self.assertEqual(payload["dest"], "docs/plans/archive/shipped/p.md")
+            mv.assert_called_once()
+
+    def test_refuses_non_shipped(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo(d, PARTIAL_BODY, present=False)
+            with mock.patch("commands.plan_archive.archive_lib.git_state.git_mv") as mv:
+                rc, out = _run(root, ["--repo=x", "--yes", "--json",
+                                      "--", "docs/plans/p.md"])
+            self.assertEqual(rc, 0)
+            self.assertEqual(json.loads(out)["outcome"], "refused_not_shipped")
+            mv.assert_not_called()
+
+    def test_collision_skips(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo(d, SHIPPED_BODY)
+            dest = root / "docs/plans/archive/shipped"
+            dest.mkdir(parents=True)
+            (dest / "p.md").write_text("# existing")
+            with mock.patch("commands.plan_archive.archive_lib.git_state.git_mv") as mv:
+                rc, out = _run(root, ["--repo=x", "--yes", "--json",
+                                      "--", "docs/plans/p.md"])
+            self.assertEqual(rc, 0)
+            self.assertEqual(json.loads(out)["outcome"], "skipped_collision")
+            mv.assert_not_called()
+
+    def test_non_tty_without_yes_declines(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo(d, SHIPPED_BODY)
+            with mock.patch("commands.plan_archive.archive_lib.git_state.git_mv") as mv:
+                rc, out = _run(root, ["--repo=x", "--", "docs/plans/p.md"])
+            self.assertEqual(rc, 0)
+            mv.assert_not_called()   # prompt defaults to "no" on non-TTY
+
+    def test_missing_rel_errors(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo(d, SHIPPED_BODY)
+            rc, _ = _run(root, ["--repo=x", "--yes", "--json",
+                                "--", "docs/plans/nope.md"])
+            self.assertEqual(rc, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,127 @@
+"""plan-status --include-archived emits archived docs (tagged) in --json and
+keeps them out of the live human render; --archive-shipped batch-archives."""
+import io
+import json
+import sys
+import tempfile
+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_status
+
+SHIPPED = "# P\n\n**Files:**\n- Create: `src/a.ts`\n- [x] Step 1\n"
+
+
+def _repo(d):
+    root = Path(d)
+    (root / "docs/plans").mkdir(parents=True)
+    (root / "docs/plans/live.md").write_text(SHIPPED)
+    (root / "src").mkdir()
+    (root / "src/a.ts").write_text("export const a = 1")
+    (root / "docs/plans/archive/shipped").mkdir(parents=True)
+    (root / "docs/plans/archive/shipped/old.md").write_text(SHIPPED)
+    return root
+
+
+def _run(root, args):
+    with mock.patch("commands.plan_status.git_state.path_last_commit_date",
+                    return_value=None), \
+         mock.patch("commands.plan_status.Path.cwd", return_value=root):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = plan_status.run(args)
+    return rc, buf.getvalue()
+
+
+class IncludeArchivedTest(unittest.TestCase):
+    def test_json_without_flag_omits_archived(self):
+        with tempfile.TemporaryDirectory() as d:
+            rc, out = _run(_repo(d), ["--json"])
+            rels = [r["rel"] for r in json.loads(out)["docs"]]
+            self.assertEqual(rels, ["docs/plans/live.md"])
+
+    def test_json_with_flag_includes_tagged_archived(self):
+        with tempfile.TemporaryDirectory() as d:
+            rc, out = _run(_repo(d), ["--json", "--include-archived"])
+            by_rel = {r["rel"]: r for r in json.loads(out)["docs"]}
+            self.assertIn("docs/plans/archive/shipped/old.md", by_rel)
+            arch = by_rel["docs/plans/archive/shipped/old.md"]
+            self.assertTrue(arch["archived"])
+            self.assertEqual(arch["archive_kind"], "shipped")
+            self.assertFalse(by_rel["docs/plans/live.md"]["archived"])
+
+
+LIEGAP = "# L\n\n**Files:**\n- Create: `src/b.ts`\n- [ ] Step 1\n- [ ] Step 2\n"
+
+
+def _repo_batch(d):
+    root = Path(d)
+    (root / "docs/plans").mkdir(parents=True)
+    (root / "docs/plans/clean.md").write_text(SHIPPED)
+    (root / "docs/plans/liegap.md").write_text(LIEGAP)
+    (root / "src").mkdir()
+    (root / "src/a.ts").write_text("export const a = 1")  # clean shipped
+    (root / "src/b.ts").write_text("export const b = 1")  # liegap shipped (0/2 boxes)
+    return root
+
+
+class ArchiveShippedBatchTest(unittest.TestCase):
+    def test_batch_json_archives_clean_excludes_liegap(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo_batch(d)
+            with mock.patch("commands.plan_status.archive_lib.git_state.git_mv",
+                            return_value=True):
+                rc, out = _run(root, ["--archive-shipped", "--yes", "--json"])
+            self.assertEqual(rc, 0)
+            payload = json.loads(out)
+            self.assertEqual(payload["action"], "archive_shipped")
+            self.assertEqual([a["rel"] for a in payload["archived"]],
+                             ["docs/plans/clean.md"])
+            self.assertEqual([x["rel"] for x in payload["lie_gap_excluded"]],
+                             ["docs/plans/liegap.md"])
+
+    def test_batch_include_lie_gap_archives_both(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo_batch(d)
+            with mock.patch("commands.plan_status.archive_lib.git_state.git_mv",
+                            return_value=True):
+                rc, out = _run(root, ["--archive-shipped", "--include-lie-gap",
+                                      "--yes", "--json"])
+            archived = sorted(a["rel"] for a in json.loads(out)["archived"])
+            self.assertEqual(archived,
+                             ["docs/plans/clean.md", "docs/plans/liegap.md"])
+
+    def test_footer_hint_lists_shipped_count(self):
+        with tempfile.TemporaryDirectory() as d:
+            rc, out = _run(_repo(d), [])   # human render
+            self.assertIn("1 shipped", out)
+            self.assertIn("plan-archive", out)
+
+    def test_terminal_yes_skips_prompt_and_archives(self):
+        # Non-JSON terminal path: --yes must skip the y/N prompt (which defaults
+        # to "no" on non-TTY stdin) and archive, mirroring per-doc plan-archive.
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo_batch(d)
+            with mock.patch("commands.plan_status.archive_lib.git_state.git_mv",
+                            return_value=True) as mv:
+                rc, out = _run(root, ["--archive-shipped", "--yes"])
+            self.assertEqual(rc, 0)
+            mv.assert_called_once()                 # clean.md archived, not skipped
+            self.assertIn("Archived 1", out)
+
+    def test_terminal_without_yes_declines_on_non_tty(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = _repo_batch(d)
+            with mock.patch("commands.plan_status.archive_lib.git_state.git_mv") as mv:
+                rc, out = _run(root, ["--archive-shipped"])
+            self.assertEqual(rc, 0)
+            mv.assert_not_called()                  # prompt defaults to no
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -78,6 +78,8 @@ class _Doc:
         d.rel = rel
         d.kind = kind
         d.path = _FakePath(name)
+        d.archived = False
+        d.archive_kind = None
         return d
 
 

package/skills/work-plan/work_plan.py

@@ -53,6 +53,7 @@ SUBCOMMANDS = {
     "plan-status": "commands.plan_status",
     "--plan-status": "commands.plan_status",  # flag-style alias
     "plan-confirm": "commands.plan_confirm",
+    "plan-archive": "commands.plan_archive",
     "plan-ack": "commands.plan_ack",
     "plan-baseline": "commands.plan_baseline",
     "close-issue": "commands.close_issue",
@@ -193,6 +194,10 @@ DESCRIPTIONS = [
      "Affirm a human verdict on ONE plan/spec doc by writing `verdict_override` into its YAML frontmatter — FRONTMATTER-ONLY (never the body, manifest, checkboxes, or status banner) (#286). plan-status then pins that verdict over the mechanical one and silences the 'shipped but boxes unchecked' lie-gap. Use when a plan genuinely shipped but its phase checkboxes were never ticked, so the red lie-gap X is a false alarm. `<rel>` is the repo-relative doc path from `plan-status --json`. On a PUBLIC repo it prints a confirm heads-up + token and exits (re-run with --confirm=<token>) — the VS Code viewer surfaces this as a modal. --clear removes the override.",
      "When the Plans view flags a genuinely-done plan with a lie-gap (red X) only because nobody ticked its checkboxes — confirm it instead of hand-ticking 24 boxes.",
      "/work-plan plan-confirm --repo=myproject --verdict=shipped -- docs/superpowers/plans/2026-03-16-idea-mode-ui.md"),
+    ("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. `<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-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.",
@@ -274,9 +279,9 @@ def _print_help() -> int:
     print("  Backfill priorities    →  /work-plan suggest-priorities --repo=myproject")
     print()
     print("=" * 80)
-    print(f"Config: ~/.claude/work-plan/config.yml  (or ~/.agents/work-plan/config.yml on Codex)")
-    print(f"Docs:   See the toolkit README for full setup, requirements, and platform-specific install.")
-    print(f"Meta:   --help / -h · --version / -v")
+    print("Config: ~/.claude/work-plan/config.yml  (or ~/.agents/work-plan/config.yml on Codex)")
+    print("Docs:   See the toolkit README for full setup, requirements, and platform-specific install.")
+    print("Meta:   --help / -h · --version / -v")
     return 0
 
 
@@ -291,7 +296,7 @@ def main(argv: list[str]) -> int:
         return 0
     if sub not in SUBCOMMANDS:
         print(f"unknown subcommand '{sub}'", file=sys.stderr)
-        print(f"Run 'python3 work_plan.py --help' for usage.", file=sys.stderr)
+        print("Run 'python3 work_plan.py --help' for usage.", file=sys.stderr)
         return 2
     try:
         module = __import__(SUBCOMMANDS[sub], fromlist=["run"])