@stylusnexus/work-plan 2026.6.21 → 2026.6.24

package/README.md

@@ -115,6 +115,8 @@ flowchart TB
 
 > **`brief` and `orient` annotate blocked issues with `⊘ blocked by #N`** — read-only, surfaced from GitHub's native dependency edges, nothing is written back. Cross-repo blockers show as `owner/repo#N`; same-repo duplicates of manually-declared blockers are deduplicated.
 
+> **A manual `blockers:` entry can be a free-text note, not just an issue number.** Normally a blocker is an issue number (`- 5550` or `- "#5550"`), which the VS Code dependency graph draws as a `blocks` edge. But it can also be prose (e.g. `- "gated on the cost go/no-go verdict"`) for when the blocker isn't a single issue. Free-text blockers still mark the track blocked and render as prose in `brief`/`orient` and the detail panel — but they don't draw a graph edge, so prefer an issue number when there is one.
+
 > **GitHub access is read-only by default, with three explicit, opt-in write actions.** Issue *data* always comes from read-only `gh` calls (`gh issue list`, `gh issue view`), and every routine write (frontmatter, status table, session log) goes to your local markdown files only. The three GitHub-*mutating* actions are all opt-in and gated: `plan-status --issues` **creates** a GitHub issue per partial plan (`gh issue create`, prompts before opening); `close-issue` (#305) **closes** an issue via `gh issue close` — for the common case where a PR merged to `dev` left its issue OPEN (GitHub auto-closes only from the default branch), with the VS Code viewer firing a mandatory "Close on GitHub? — cannot be undone" modal on every close; and `in-progress` (#271) **adds or removes** the `work-plan:in-progress` label on an issue, public-repo gated via the confirm-token flow. Nothing else touches GitHub state.
 
 ## Shared tracks
@@ -312,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 |
@@ -539,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. |
@@ -565,7 +569,7 @@ 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…**.
+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…**, multi-select several (Cmd/Ctrl/Shift-click) → **Archive Plan…** to archive the batch behind one confirm, or a repo → **Archive shipped plans…** to sweep them all.
 
 ## Version
 

package/VERSION

@@ -1 +1 @@
-2026.06.21+4cab67a
+2026.06.24+b047035

package/package.json

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

@@ -6,7 +6,7 @@ Manifest-less (prose) docs are flagged 👻 for the Phase 1b LLM pass.
 """
 import json
 import sys
-from datetime import date
+from datetime import date, timedelta
 from pathlib import Path
 
 from lib import config as config_mod
@@ -120,13 +120,41 @@ def _declared_paths_on_disk(decls, repo_root) -> list:
     return out
 
 
-def _evaluate(doc, repo_root, today, dead_days, stall_days) -> dict:
+def _committed_since_from_map(last_dates, plan_date, repo_root):
+    """`committed_since(rel)` served from the batched date map (#391), mirroring
+    manifest.score_manifest's default: with no plan date, degrade to a filesystem
+    existence check; otherwise "committed on/after plan_date" is `last-commit-date
+    >= plan_date - 1 day` (the same 1-day window `path_committed_since` widens to,
+    so same-day Modify commits still count)."""
+    if plan_date is None:
+        return lambda rel: (Path(repo_root) / rel).exists()
+    cutoff = plan_date - timedelta(days=1)
+
+    def committed_since(rel):
+        dt = last_dates.get(rel)
+        return dt is not None and dt.date() >= cutoff
+
+    return committed_since
+
+
+def _evaluate(doc, repo_root, today, dead_days, stall_days, last_dates=None) -> dict:
     text = _read(doc.path)
     decls = manifest.parse_declared_paths(text)
     pdate = manifest.plan_date_from_filename(doc.path.name)
-    score = manifest.score_manifest(decls, repo_root, pdate)
+    # `last_dates` is the batched {path: datetime} map precomputed in run() (#391)
+    # over every doc rel AND every declared path — one chunked git walk for the
+    # whole repo. When present, serve score_manifest's per-Modify-path
+    # `committed_since` (the real O(n) cost — 1434 git spawns on CritForge), the
+    # doc's own last-commit date, and the partial-staleness clock from it: zero
+    # git spawns in this loop. When absent (direct callers / tests), fall back to
+    # the per-path git calls so behavior is unchanged.
+    cs = _committed_since_from_map(last_dates, pdate, repo_root) if last_dates is not None else None
+    score = manifest.score_manifest(decls, repo_root, pdate, committed_since=cs)
     done, total_chk = manifest.count_checkboxes(text)
-    last_dt = git_state.path_last_commit_date(doc.rel, repo_root)
+    if last_dates is not None:
+        last_dt = last_dates.get(doc.rel)
+    else:
+        last_dt = git_state.path_last_commit_date(doc.rel, repo_root)
     last_d = last_dt.date() if last_dt else None
     if decls and manifest.out_of_tree_ratio(decls, repo_root) >= verdict_mod.FOREIGN_RATIO:
         v = verdict_mod.Verdict(
@@ -151,7 +179,11 @@ def _evaluate(doc, repo_root, today, dead_days, stall_days) -> dict:
     if v.label == "partial":
         on_disk = _declared_paths_on_disk(decls, repo_root)
         if on_disk:
-            manifest_dt = git_state.paths_last_commit_date(on_disk, repo_root)
+            if last_dates is not None:
+                ds = [last_dates[p] for p in on_disk if p in last_dates]
+                manifest_dt = max(ds) if ds else None
+            else:
+                manifest_dt = git_state.paths_last_commit_date(on_disk, repo_root)
             if manifest_dt is None:
                 stalled = True  # present on disk but never committed
             else:
@@ -324,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
 
@@ -347,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({
@@ -381,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
 
@@ -462,7 +501,22 @@ def run(args: list) -> int:
         docs = [d for d in docs if d.kind == type_filter]
 
     stall_days = _resolve_stall_days(flags)
-    rows = [_evaluate(d, repo_root, today, dead_days, stall_days) for d in docs]
+    # Batch EVERY git date the scan needs — each doc's own rel plus every declared
+    # path (Modify paths drive score_manifest's committed_since, the real O(n)
+    # cost) — into one chunked git walk (#391), instead of a subprocess per path.
+    # This is what hung the Plans view on large repos (CritForge: 391 docs +
+    # 1434 declared paths = ~1800 git spawns → ~40s, now a handful of walks).
+    batch_paths = set()
+    for d in docs:
+        batch_paths.add(d.rel)
+        try:
+            for dp in manifest.parse_declared_paths(_read(d.path)):
+                batch_paths.add(dp.path)
+        except OSError:
+            pass
+    last_dates = git_state.paths_last_commit_dates(sorted(batch_paths), repo_root)
+    rows = [_evaluate(d, repo_root, today, dead_days, stall_days, last_dates)
+            for d in docs]
 
     if flags.get("--llm"):
         if flags.get("--apply"):

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/blockers.py

@@ -0,0 +1,40 @@
+"""Track blocker normalization — the Python sibling of the viewer's blockerIssue().
+
+A `blockers:` frontmatter entry is usually an issue number, but it may also be a
+free-text note (e.g. "gated on the cost go/no-go verdict, needs #5548 telemetry").
+Consumers that render a blocker with a leading `#` must funnel it through
+`blocker_display` first, or a prose blocker prints as `#<sentence>`; the next-up
+gate must funnel it through `blocker_issue`, or a string-form ref ("5550") never
+matches the integer issue number it should exclude.
+"""
+
+import re
+
+_ISSUE_REF = re.compile(r"^\s*#?(\d+)\s*$")
+
+
+def blocker_issue(value):
+    """The issue number a blocker refers to, or None for free-text.
+
+    Mirrors the viewer's `blockerIssue`: a bare int, "5550", or "#5550" resolves
+    to the number; anything else (prose, even when it embeds a `#5550`) is
+    free-text. A leading-zero string like "007" is treated as free-text rather
+    than silently coerced to 7. `bool` is rejected (it is an int subclass).
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        m = _ISSUE_REF.match(value)
+        if m is not None:
+            digits = m.group(1)
+            if str(int(digits)) == digits:  # reject leading-zero "007"
+                return int(digits)
+    return None
+
+
+def blocker_display(value):
+    """How to show a blocker: `#N` for an issue ref, the prose itself otherwise."""
+    n = blocker_issue(value)
+    return f"#{n}" if n is not None else str(value)

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

@@ -254,6 +254,92 @@ def paths_last_commit_date(rel_paths, repo_path: Path) -> Optional[datetime]:
         return None
 
 
+# A `%cI` commit line ("2026-06-19T10:00:00-07:00") vs a path line, so the
+# batched walk below can tell which is which without a sentinel (plan/spec doc
+# paths never look like an ISO timestamp).
+_ISO_DT_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}")
+
+
+def _is_inrepo_rel(p: str) -> bool:
+    """True if `p` is a repo-relative path that stays inside the repo — safe to
+    pass to `git log -- <p>`. Rejects empty, absolute (`/…`), home (`~…`),
+    backslash, and any `..` that escapes the root (a foreign plan's off-tree
+    declared path). git would exit 128 on those, poisoning the batch."""
+    if not p or p[0] in "/~" or "\\" in p:
+        return False
+    depth = 0
+    for part in p.split("/"):
+        if part in ("", "."):
+            continue
+        if part == "..":
+            depth -= 1
+            if depth < 0:
+                return False
+        else:
+            depth += 1
+    return True
+
+
+def paths_last_commit_dates(rel_paths, repo_path: Path) -> dict:
+    """Most-recent commit datetime touching EACH of `rel_paths`, in a SINGLE
+    `git log` walk (#391) — vs one `path_last_commit_date` subprocess per path,
+    whose spawn overhead makes a many-doc scan O(docs) in process startups.
+
+    Returns {rel_path: datetime} for paths with at least one commit; a path
+    never committed is omitted. `git log` walks newest-first, so the first
+    commit that touches a path is its last touch. Never raises (None/bad-repo/
+    git-error all yield the partial-or-empty map).
+    """
+    out: dict = {}
+    if not rel_paths or not repo_path or not Path(repo_path).exists():
+        return out
+    # Drop off-tree paths (absolute, ~, ..-escape) BEFORE the git call: an
+    # out-of-repo pathspec makes `git log -- <…>` exit 128, which would poison
+    # the WHOLE chunk and silently lose every other path in it. Such paths can't
+    # have a commit in this repo anyway, so omitting them is correct (#391).
+    paths = [p for p in dict.fromkeys(rel_paths) if _is_inrepo_rel(p)]
+    if not paths:
+        return out
+    # Chunk the pathspec so a many-doc repo (1000s of declared paths) can't blow
+    # past the OS arg-length limit; each chunk is one `git log` walk.
+    for i in range(0, len(paths), _BATCH_CHUNK):
+        _collect_last_dates(paths[i:i + _BATCH_CHUNK], repo_path, out)
+    return out
+
+
+_BATCH_CHUNK = 400
+
+
+def _collect_last_dates(paths, repo_path, out: dict) -> None:
+    """One `git log --name-only` walk over `paths`; record each path's newest
+    commit datetime into `out`. core.quotePath=false → non-ASCII paths print raw
+    so they match the rel strings exactly."""
+    remaining = set(paths)
+    proc = _git(repo_path, "-c", "core.quotePath=false",
+                "log", "--format=%cI", "--name-only", "--", *paths)
+    if proc is None or proc.returncode != 0:
+        return
+    cur = None
+    for line in proc.stdout.splitlines():
+        if not line:
+            continue
+        if _ISO_DT_RE.match(line):
+            cur = line
+            continue
+        if cur and line in remaining:
+            try:
+                # %cI carries a numeric tz offset (often negative, e.g. -07:00).
+                # Parse it, then drop tzinfo for a consistent NAIVE datetime — so
+                # callers can compare/max() across paths (a +offset and a -offset
+                # mix would otherwise be aware-vs-naive). .date() is unchanged.
+                out[line] = datetime.fromisoformat(cur).replace(tzinfo=None)
+            except ValueError:
+                pass
+            remaining.discard(line)
+            if not remaining:
+                break
+
+
 def path_committed_since(rel_path: str, since: date, repo_path: Path) -> bool:
     """True if `rel_path` has any commit on/around `since` or later (a datetime.date).
 
@@ -272,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/lib/next_up.py

@@ -40,6 +40,7 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Iterable, Optional
 
+from lib.blockers import blocker_issue
 from lib.github_state import extract_priority, short_milestone
 
 PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
@@ -151,7 +152,10 @@ def suggest_next_up(
         List of issue numbers, highest-ranked first. Empty if nothing
         qualifies (e.g., everything closed or blocked).
     """
-    blockers = set(blocker_nums or [])
+    # Normalize blockers to issue numbers: a string-form ref ("5550"/"#5550")
+    # must still exclude issue 5550, and a free-text blocker resolves to None
+    # (dropped) so it harmlessly gates nothing.
+    blockers = {n for n in (blocker_issue(b) for b in (blocker_nums or [])) if n is not None}
     in_progress = set(in_progress_nums or [])
     # Resolve order: None → default preset; unknown names in list → skipped.
     effective_order = order if order is not None else PRESETS[DEFAULT_PRESET]

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

@@ -1,5 +1,7 @@
 """Compose terminal output strings."""
 
+from lib.blockers import blocker_display
+
 
 def time_aware_framing(gap_seconds: int, current_hour: int, handoff_today: bool = True) -> str:
     """Adapt framing to gap-since-last-activity + hour."""
@@ -66,7 +68,9 @@ def render_track_row(t: dict) -> str:
     if t["blockers"]:
         for b in t["blockers"]:
             reason = b.get("reason", "manually flagged")
-            lines.append(f"    Blocker:    #{b['number']} — {reason}")
+            # blocker_display: `#N` for an issue ref, the prose verbatim for a
+            # free-text blocker (a raw `#{number}` would print `#<sentence>`).
+            lines.append(f"    Blocker:    {blocker_display(b['number'])} — {reason}")
     else:
         lines.append("    Blockers:   none")
 

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_blockers.py

@@ -0,0 +1,47 @@
+"""Tests for lib.blockers — blocker_issue / blocker_display normalization."""
+
+import unittest
+
+from lib.blockers import blocker_issue, blocker_display
+
+
+class TestBlockerIssue(unittest.TestCase):
+    def test_bare_int_is_its_own_ref(self):
+        self.assertEqual(blocker_issue(5550), 5550)
+
+    def test_pure_id_strings_resolve(self):
+        self.assertEqual(blocker_issue("5550"), 5550)
+        self.assertEqual(blocker_issue("#5550"), 5550)
+        self.assertEqual(blocker_issue("  #5550 "), 5550)
+
+    def test_prose_is_free_text_even_with_embedded_ref(self):
+        # Must NOT extract 5550 — it's an active next_up item being described.
+        self.assertIsNone(
+            blocker_issue("#5550 selective routing is gated on the verdict, needs #5548")
+        )
+        self.assertIsNone(blocker_issue("waiting on design review"))
+
+    def test_leading_zero_is_free_text(self):
+        # "007" must not silently become issue 7.
+        self.assertIsNone(blocker_issue("007"))
+
+    def test_bool_and_empty_are_free_text(self):
+        self.assertIsNone(blocker_issue(True))
+        self.assertIsNone(blocker_issue(""))
+        self.assertIsNone(blocker_issue("#"))
+
+
+class TestBlockerDisplay(unittest.TestCase):
+    def test_issue_ref_gets_hash_prefix(self):
+        self.assertEqual(blocker_display(5550), "#5550")
+        self.assertEqual(blocker_display("#5550"), "#5550")
+        self.assertEqual(blocker_display("5550"), "#5550")
+
+    def test_free_text_shown_verbatim_without_hash(self):
+        prose = "gated on the cost go/no-go verdict"
+        self.assertEqual(blocker_display(prose), prose)
+        self.assertNotIn("#", blocker_display(prose))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,144 @@
+"""Batched last-commit-date lookup (#391): one `git log` walk yields the latest
+commit datetime per path, replacing N per-path subprocess spawns. Offline —
+`_git` is mocked, no real git invoked."""
+import io
+import json as _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 lib import git_state
+from commands import plan_status
+
+
+class _FakeProc:
+    def __init__(self, stdout, returncode=0):
+        self.stdout = stdout
+        self.returncode = returncode
+        self.stderr = ""
+
+
+# `git log --format=%cI --name-only` over three paths, newest-first. a.md last
+# touched in the newest commit; b.md too; c.md only in the older commit.
+LOG = (
+    "2026-06-19T10:00:00-07:00\n"
+    "\n"
+    "docs/plans/a.md\n"
+    "docs/plans/b.md\n"
+    "2026-06-10T09:00:00-07:00\n"
+    "\n"
+    "docs/plans/a.md\n"
+    "docs/plans/c.md\n"
+)
+
+
+class PathsLastCommitDatesTest(unittest.TestCase):
+    def test_single_call_maps_each_path_to_its_latest(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=_FakeProc(LOG)) as g:
+            res = git_state.paths_last_commit_dates(
+                ["docs/plans/a.md", "docs/plans/b.md", "docs/plans/c.md"],
+                Path("/repo"))
+        g.assert_called_once()                       # ONE git spawn, not three
+        self.assertEqual(res["docs/plans/a.md"].date().isoformat(), "2026-06-19")
+        self.assertEqual(res["docs/plans/b.md"].date().isoformat(), "2026-06-19")
+        self.assertEqual(res["docs/plans/c.md"].date().isoformat(), "2026-06-10")
+
+    def test_batched_call_uses_name_only_walk(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=_FakeProc(LOG)) as g:
+            git_state.paths_last_commit_dates(["docs/plans/a.md"], Path("/repo"))
+        args = g.call_args.args
+        self.assertIn("--name-only", args)
+        self.assertIn("log", args)
+        self.assertIn("docs/plans/a.md", args)       # path passed through
+
+    def test_uncommitted_path_omitted(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=_FakeProc(LOG)):
+            res = git_state.paths_last_commit_dates(
+                ["docs/plans/a.md", "docs/plans/never.md"], Path("/repo"))
+        self.assertIn("docs/plans/a.md", res)
+        self.assertNotIn("docs/plans/never.md", res)  # no commit → omitted
+
+    def test_empty_input_no_git_call(self):
+        with mock.patch("lib.git_state._git") as g:
+            self.assertEqual(git_state.paths_last_commit_dates([], Path("/repo")), {})
+        g.assert_not_called()
+
+    def test_git_failure_returns_empty(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=_FakeProc("", returncode=128)):
+            self.assertEqual(
+                git_state.paths_last_commit_dates(["docs/plans/a.md"], Path("/repo")), {})
+
+    def test_offtree_paths_filtered_before_git(self):
+        # An off-tree pathspec (../, absolute, ~) makes `git log` exit 128 and
+        # poison the whole chunk; they must be dropped before the call (#391).
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=_FakeProc(LOG)) as g:
+            res = git_state.paths_last_commit_dates(
+                ["docs/plans/a.md", "../escape.md", "/abs/x.md", "~/h.md",
+                 "a/../../b.md"], Path("/repo"))
+        passed = g.call_args.args
+        self.assertIn("docs/plans/a.md", passed)
+        for bad in ("../escape.md", "/abs/x.md", "~/h.md", "a/../../b.md"):
+            self.assertNotIn(bad, passed)        # never reaches git
+        self.assertIn("docs/plans/a.md", res)
+
+    def test_all_offtree_no_git_call(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git") as g:
+            self.assertEqual(
+                git_state.paths_last_commit_dates(["../x", "/y"], Path("/repo")), {})
+        g.assert_not_called()
+
+    def test_none_proc_returns_empty(self):
+        with mock.patch("lib.git_state.Path.exists", return_value=True), \
+             mock.patch("lib.git_state._git", return_value=None):
+            self.assertEqual(
+                git_state.paths_last_commit_dates(["docs/plans/a.md"], Path("/repo")), {})
+
+
+class PlanStatusBatchesTest(unittest.TestCase):
+    """run() must use the ONE batched call, not a per-doc git spawn (#391)."""
+
+    def _repo(self, d):
+        root = Path(d)
+        (root / "docs/plans").mkdir(parents=True)
+        # A Modify path is what drove the per-path committed_since git spawns.
+        (root / "docs/plans/a.md").write_text(
+            "# A\n\n- Create: `src/a.ts`\n- Modify: `src/x.ts`\n")
+        (root / "docs/plans/b.md").write_text("# B\n\n- Create: `src/b.ts`\n")
+        return root
+
+    def test_run_batches_one_call_no_per_doc_spawn(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = self._repo(d)
+            with mock.patch("commands.plan_status.Path.cwd", return_value=root), \
+                 mock.patch("commands.plan_status.git_state.paths_last_commit_dates",
+                            return_value={}) as batch, \
+                 mock.patch("commands.plan_status.git_state.path_last_commit_date") as per, \
+                 mock.patch("commands.plan_status.git_state.paths_last_commit_date") as per_multi:
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = plan_status.run(["--json"])
+            self.assertEqual(rc, 0)
+            batch.assert_called_once()      # one git walk for all docs + declared paths
+            per.assert_not_called()         # no per-doc last-commit spawn
+            per_multi.assert_not_called()   # no per-partial staleness spawn
+            # committed_since is served from the injected map (run() passes a
+            # closure to score_manifest), so its per-Modify-path git fallback
+            # never runs — that was the real O(n) cost.
+            docs = _json.loads(buf.getvalue())["docs"]
+            self.assertEqual(len(docs), 2)
+
+
+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

@@ -25,11 +25,23 @@ class ArchiveTest(unittest.TestCase):
         return root
 
     def _run(self, root, args, mv_ok=True):
-        # stale last-commit (well beyond DEAD_DAYS) so the absent-file plan is dead
+        # stale last-commit (well beyond DEAD_DAYS) so the absent-file plan is dead.
+        # 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
         with mock.patch("commands.plan_status.git_state.path_last_commit_date",
-                        return_value=datetime(2026, 1, 1)), \
+                        return_value=stale), \
+             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)