@stylusnexus/work-plan 2026.6.22 → 2026.6.24

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 |
@@ -541,7 +543,7 @@ 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-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.06.24+b047035

package/package.json

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

@@ -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/lib/archive.py

@@ -1,6 +1,9 @@
-"""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."""
+"""The archive move primitive: collision-checked move of a doc into
+archive/<kind>/. For tracked files the move is a history-preserving `git mv`
+(staged rename); for untracked/gitignored files it falls back to a plain
+filesystem move. Eligibility (is-this-shipped) is the caller's job — this
+only moves files."""
+import shutil
 from pathlib import Path
 
 from lib import git_state
@@ -8,14 +11,26 @@ from lib import reconcile_actions
 
 
 def move_to_archive(rel: str, repo_root, kind: str):
-    """git-mv `rel` into archive/<kind>/. Returns:
-      "archived"          on a clean move,
-      "skipped_collision" if the destination already exists (never overwrite),
-      None                if git_mv failed for any other reason (hard error).
+    """Move `rel` into archive/<kind>/. Returns:
+      "archived"          tracked file: history-preserving `git mv` (staged rename),
+      "archived_local"    untracked/gitignored file: plain filesystem move,
+      "skipped_collision" destination already exists (never overwrite),
+      None                hard failure (git mv failed on a tracked file, or OSError
+                          on an untracked file).
     """
     dest = reconcile_actions.archive_dest(rel, kind)
     if (Path(repo_root) / dest).exists():
         return "skipped_collision"
-    if git_state.git_mv(rel, dest, repo_root):
-        return "archived"
-    return None
+    if git_state.is_tracked(rel, Path(repo_root)):
+        if git_state.git_mv(rel, dest, repo_root):
+            return "archived"
+        return None
+    # Untracked / gitignored — plain filesystem move.
+    src_path = Path(repo_root) / rel
+    dst_path = Path(repo_root) / dest
+    try:
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src_path), str(dst_path))
+        return "archived_local"
+    except OSError:
+        return None

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

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

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

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

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

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

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

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

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

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