@stylusnexus/work-plan 2026.6.11-2 → 2026.6.13

package/README.md

@@ -511,11 +511,12 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `orient [track]` (alias: `where-was-i`) | Read-only paste block. With a track name: ~15-line track summary (priority, last session, next pick, git state). With no track: cwd snapshot (branch, recent commits, modified files) for non-track work. Add `--pick` for the interactive track picker. |
 | `slot <issue-num> [track]` | A new GitHub issue should belong to a track — adds it to the track's `github.issues` list. Non-interactive flags: `--move`/`--no-move` (relocate the issue off its prior track, or leave it; default no-move), `--confirm=<token>` (public-repo gate, see below). |
 | `close <track> [--state=shipped\|parked\|abandoned] [--note=<text>]` | Mark track shipped, parked, or abandoned. Moves to `archive/<state>/` for shipped/abandoned. Pass `--state=` (and an optional `--note=`) to run without prompts. |
-| `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Sync issue STATE (open/closed, status labels) from GitHub into the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." For a **canonical** table it re-derives the whole block from live data, milestone-ordered (active milestone first; see `canonicalize`), so the table self-heals and stays grouped instead of decaying; narrative (non-canonical) tables are updated conservatively in place. `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
+| `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Sync issue STATE (open/closed, status labels) from GitHub into the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." For a **canonical** table it re-derives the whole block from live data, milestone-ordered (active milestone first; see `canonicalize`), so the table self-heals and stays grouped instead of decaying; narrative (non-canonical) tables are updated conservatively in place. If the live fetch comes back incomplete (GitHub timeout/permission error, or a frontmatter issue that no longer resolves), that track is **skipped and left untouched** rather than rewriting valid rows as `(not fetched)`, and the command exits nonzero so sweeps can flag the degraded run. `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
 | `hygiene [--repo=<key>]` | Weekly all-in-one: `refresh-md` + `reconcile` + `duplicates`. With `--repo=<key>`, steps 1 and 2 scope to that repo and the global `duplicates` step is skipped. |
 | `list [--all] [--sort=recent\|priority]` | List active tracks (or all including parked/archived). `--sort=recent` orders by `last_touched` (most recent first); `--sort=priority` orders by `launch_priority` (P0→P3) with recency as tiebreaker. Default keeps discovery order. |
 | `init <path> [--priority=P0..P3] [--milestone=<m>]` | Add frontmatter to a brand-new track .md file (the file must already exist). Pass `--priority=`/`--milestone=` to skip the prompts. |
-| `init-repo <key> --github=<slug> [--local=<path>]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. `--github` is required; `--local` is optional. |
+| `init-repo <key> --github=<slug> [--local=<path>] [--update [--clear-local]]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. `--github` is required for an add; `--local` is optional. `--update` on an existing key changes its local/github; `--update --clear-local` forgets the saved local path (keeps github + other fields). `--clear-local` and `--local` are mutually exclusive. |
+| `remove-repo <key>` | Unregister a repo: delete its block from your config. **Config-only** — the notes folder, any tracks, and the local clone are left untouched (a notes folder or tracks that referenced it are now orphaned and can be removed by hand). Completes the add/update/remove trio with `init-repo`. |
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `rename-track <old-slug \| old@repo> <new-slug> [--repo=<key>] [--fix-refs] [--commit]` | Rename an active track's slug: moves its `.md` file and updates the frontmatter `track` field + `last_touched`. Validates `<new-slug>` like `new-track` and rejects a name already taken in the same repo/tier. For shared tracks, `--commit` stages + commits the move (otherwise it prints a "commit to share" hint). `--fix-refs` rewrites sibling tracks' `depends_on` that reference the old slug; without it they're just warned about. Archived tracks are immutable. Public-repo gated. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
@@ -538,7 +539,11 @@ Every write verb the VS Code extension drives runs **without a TTY** — explici
 
 `needs_confirm` fails **closed** — unknown visibility prompts too. An all-private team can opt out of the *unknown-visibility* case (e.g. when a `gh` lookup flakes) by setting `assume_private_when_unknown: true` in `~/.claude/work-plan/config.yml`; **public repos always prompt regardless.**
 
-`export --json` is the viewer's read surface (schema 1): every frontmatter'd track plus an additive `untracked` list of open issues that no track references, per repo.
+`export --json` is the viewer's read surface (schema 1): every frontmatter'd track plus an additive `untracked` list of open issues that no track references, per repo. It also emits a top-level `repos` list — every configured repo (`folder`/`repo`/`local`/`has_local`/`visibility`), tracked or not — so the viewer can show a freshly registered repo in the sidebar independent of whether it has any tracks yet.
+
+`list-open-issues --repo=<owner/name> [--exclude=<csv>]` is a second viewer read surface: it emits a repo's **open** issues as JSON (`{repo, issues:[…]}`, the same per-issue shape as `export`). The extension's **Slot** command uses it to offer a pick-list instead of a typed number; `--exclude` drops the track's current issues so they don't reappear. Unlike `export`'s `untracked` (open issues in *no* track), this includes issues tracked by *other* tracks — they're valid slot targets. Read-only.
+
+`plan-status --json` is the viewer's **Plans view** read surface: alongside each doc's verdict it now also emits `manifest_last_touched` (the most recent commit date across the plan's declared files), `stalled`, `lie_gap`, `unchecked_items`, and `stall_days`. The staleness window honors `stall_days:` in `~/.claude/work-plan/config.yml` and a `--stall-days=<n>` flag (precedence: flag → config → default 14). The viewer consumes these to flag plans whose declared-file build has gone cold — a `partial` plan with no recent commit on its manifest ("stalled") — and plans scored shipped whose own phase checkboxes are mostly unticked ("lie-gap").
 
 ## Version
 

package/VERSION

@@ -1 +1 @@
-2026.06.11+60c2651
+2026.06.13+627d944

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.11-2",
+  "version": "2026.6.13",
   "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/commands/export.py

@@ -1,7 +1,7 @@
 """export subcommand — emit the viewer-ready JSON read surface."""
 import json
 from datetime import datetime
-from lib.config import load_config, ConfigError
+from lib.config import load_config, ConfigError, resolve_local_path_for_folder
 from lib.tracks import discover_tracks
 from lib.github_state import fetch_export_issues, fetch_open_issues, repo_visibility
 from lib.export_model import build_export
@@ -60,10 +60,28 @@ def run(args: list[str]) -> int:
         open_rows = fetch_open_issues(repo)
         untracked_by_repo[repo] = [r for r in open_rows if r.get("number") not in tracked]
 
+    # Every CONFIGURED repo, regardless of whether any track references it (#288).
+    # Lets the viewer show a registered-but-empty repo so the user can start
+    # adding tracks to it. visibility is filled here for repos no track covered.
+    config_repos = []
+    for folder, block in (cfg.get("repos") or {}).items():
+        slug = block.get("github") if isinstance(block, dict) else None
+        local = resolve_local_path_for_folder(folder, cfg)
+        if slug and slug not in visibility:
+            visibility[slug] = repo_visibility(slug)
+        config_repos.append({
+            "folder": folder,
+            "repo": slug,
+            "local": str(local) if local else None,
+            "has_local": bool(local and local.exists()),
+            "visibility": visibility.get(slug),
+        })
+
     now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
     print(json.dumps(
         build_export(tracks, issues_by_track, visibility, now,
-                     untracked_by_repo=untracked_by_repo),
+                     untracked_by_repo=untracked_by_repo,
+                     config_repos=config_repos),
         indent=2,
     ))
     return 0

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

@@ -50,10 +50,56 @@ def _report_shared_tracks(local_path: "Path | None") -> None:
         )
 
 
+def _update_existing(key: str, github: str, local: "str | None", clear_local: bool = False) -> int:
+    """Update an already-registered repo's local (and github if it differs).
+
+    Does NOT recreate the notes folder / archive dirs — they already exist.
+    Uses the same env()-via-opaque-block yq pattern as a fresh add, setting only
+    the fields that change so other keys in the block are preserved.
+
+    clear_local sets `.repos.<key>.local = null` (forget a stale checkout path)
+    while keeping github + every other field. Mutually exclusive with `local`
+    (enforced in run() before this is called).
+    """
+    updates = {}
+    if clear_local:
+        # JSON null → YAML null; the * merge overwrites local with null, leaving
+        # github + other keys intact (same opaque-env discipline as below).
+        updates["local"] = None
+    elif local:
+        updates["local"] = local
+    if github:
+        updates["github"] = github
+    if not updates:
+        print(f"ℹ Nothing to update for repo '{key}' (no --local, --clear-local, or --github given).")
+        return 0
+
+    # `key` is validated against ^[a-z][a-z0-9-]*$ in run() before this is called,
+    # so it's safe in the yq path. Field values travel as an OPAQUE env value via
+    # env() (parsed as JSON), never interpolated — uniform with the add path.
+    env = {**os.environ, "WP_REPO_UPDATES": json.dumps(updates)}
+    yq_expr = f".repos.{key} = (.repos.{key} // {{}}) * env(WP_REPO_UPDATES)"
+    try:
+        subprocess.run(
+            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True, env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return 1
+    if clear_local:
+        print(f"✓ Cleared local path for '{key}'")
+    elif local:
+        print(f"✓ Updated repo '{key}' local path → {local}")
+    else:
+        print(f"✓ Updated repo '{key}' in {DEFAULT_CONFIG_PATH}")
+    return 0
+
+
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--github", "--local"})
+    flags, positional = parse_flags(args, {"--github", "--local", "--update", "--clear-local"})
     if not positional:
-        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>]")
+        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>] [--update [--clear-local]]")
         return 2
 
     key = positional[0]
@@ -61,13 +107,23 @@ def run(args: list[str]) -> int:
         print(f"ERROR: '{key}' is not a valid key. Use lowercase letters, digits, hyphens; must start with a letter.")
         return 2
 
-    # --github is required; no prompt fallback
+    clear_local = bool(flags.get("--clear-local"))
+    local = flags.get("--local") or None
+
+    # --clear-local forgets the saved local path; pairing it with --local (which
+    # SETS a path) is contradictory.
+    if clear_local and local:
+        print("ERROR: --clear-local and --local are mutually exclusive.")
+        return 2
+
+    # --github is required for a fresh add / a github change, but --clear-local is
+    # a field-only edit on an existing block, so we don't force it there.
     github = flags.get("--github")
-    if not github or "/" not in github:
-        if not github:
-            print("ERROR: --github is required (e.g. --github=org/repo).")
-        else:
-            print("ERROR: github slug must be in the form 'org/repo'.")
+    if github and "/" not in github:
+        print("ERROR: github slug must be in the form 'org/repo'.")
+        return 2
+    if not github and not clear_local:
+        print("ERROR: --github is required (e.g. --github=org/repo).")
         return 2
 
     try:
@@ -77,19 +133,33 @@ def run(args: list[str]) -> int:
         print("\nRun ./install.sh from the toolkit root to seed your config first.")
         return 1
 
-    if key in cfg.get("repos", {}):
-        print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
-        print("Edit it manually, or pick a different key.")
-        return 1
+    update = bool(flags.get("--update"))
+    existing = cfg.get("repos", {})
 
-    # --local is optional; if absent, skip (no prompt)
-    local = flags.get("--local") or None
+    # --clear-local is an update-only operation on an existing key.
+    if clear_local:
+        if not update:
+            print("ERROR: --clear-local requires --update (it edits an existing repo).")
+            return 2
+        if key not in existing:
+            print(f"ERROR: repo '{key}' not found in {DEFAULT_CONFIG_PATH} — nothing to clear.")
+            return 1
+        return _update_existing(key, github or "", None, clear_local=True)
+
+    # --local is optional; if absent, skip (no prompt). Validate it exists.
     local_path = None
     if local:
         local_path = Path(local).expanduser()
         if not local_path.exists():
             print(f"WARN: {local_path} does not exist. Saving anyway — fix later if wrong.")
 
+    if key in existing:
+        if not update:
+            print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
+            print("Pass --update to change its local path, or pick a different key.")
+            return 1
+        return _update_existing(key, github, local)
+
     notes_root = Path(cfg["notes_root"]).expanduser()
     if not notes_root.exists():
         print(f"ERROR: notes_root {notes_root} does not exist.")

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

@@ -0,0 +1,52 @@
+"""list-open-issues subcommand — emit a repo's open issues as JSON.
+
+A read surface for the VS Code viewer's Slot command (#282): Slot adds an issue
+that is typically NOT already in the track, so the per-track export can't supply
+the candidate list. This fetches the repo's open issues live via `gh` and emits
+them in the same `Issue` shape the export uses, so the viewer can offer a
+pick-list instead of a free-typed number.
+
+Read-only. Never writes anything. The viewer passes the track's current issue
+numbers via --exclude so already-slotted issues are filtered out here.
+"""
+import json
+
+from lib.github_state import fetch_open_issues
+from lib.export_model import normalize_issue
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--repo", "--exclude"})
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print(json.dumps({"error": "list-open-issues requires --repo=<owner/name>"}))
+        return 2
+
+    exclude = _parse_exclude(flags.get("--exclude"))
+
+    # fetch_open_issues validates the slug and returns [] on any error/bad repo,
+    # so a malformed --repo yields an empty list rather than raising.
+    rows = fetch_open_issues(repo)
+    issues = [
+        normalize_issue(r) for r in rows
+        if r.get("number") not in exclude
+    ]
+    print(json.dumps({"repo": repo, "issues": issues}, indent=2))
+    return 0
+
+
+def _parse_exclude(raw) -> set:
+    """Parse the --exclude CSV (e.g. "87,91,103") into a set of ints.
+
+    Tolerates blanks and non-numeric tokens (skipped), so a stray trailing
+    comma or empty value never errors. `True` (bare --exclude) → empty set."""
+    if not raw or raw is True:
+        return set()
+    out = set()
+    for tok in str(raw).split(","):
+        tok = tok.strip()
+        if tok.isdigit():
+            out.add(int(tok))
+    return out

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

@@ -19,7 +19,7 @@ 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"}
+         "--llm", "--apply", "--archive", "--issues", "--stall-days"}
 _ORDER = ["shipped", "partial", "dead", "foreign", "manifest-less"]
 
 
@@ -35,8 +35,54 @@ def _resolve_repo_root(flags) -> Path:
     return Path.cwd()
 
 
-def _evaluate(doc, repo_root, today, dead_days) -> dict:
-    text = doc.path.read_text(encoding="utf-8", errors="replace")
+def _resolve_stall_days(flags) -> int:
+    """Precedence for the staleness threshold (#164):
+    --stall-days flag (int) -> config.yml `stall_days` (int) -> default 14.
+    A non-integer flag value falls through to the config/default tier.
+    """
+    raw = flags.get("--stall-days")
+    if raw not in (None, True):
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            pass
+    cfg_val = config_mod.load_config().get("stall_days")
+    if isinstance(cfg_val, int):
+        return cfg_val
+    return verdict_mod.STALL_DAYS
+
+
+def _read(path) -> str:
+    """Read a doc's text. Indirected so tests can patch it without a real file."""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _declared_paths_on_disk(decls, repo_root) -> list:
+    """Repo-relative declared paths that point at a real FILE inside repo_root.
+
+    Both guards matter for the staleness clock: a junk declared path like `/`
+    resolves (via `repo_root / "/"`) to the filesystem root — a directory that
+    exists — and an out-of-tree `../x` path can exist too. Either one passed to
+    `git log -- <paths…>` poisons the WHOLE call (it returns nothing), which
+    would falsely mark an actively-built plan as stalled. So require an actual
+    file (`is_file`) that resolves under repo_root."""
+    root = Path(repo_root).resolve()
+    out = []
+    for d in decls:
+        p = Path(repo_root) / d.path
+        try:
+            if not p.is_file():
+                continue
+            resolved = p.resolve()
+        except OSError:
+            continue
+        if resolved == root or root in resolved.parents:
+            out.append(d.path)
+    return out
+
+
+def _evaluate(doc, repo_root, today, dead_days, stall_days) -> 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)
@@ -48,12 +94,36 @@ def _evaluate(doc, repo_root, today, dead_days) -> dict:
             "foreign", "🧳", "declared paths point outside this repo — misfiled?")
     else:
         v = verdict_mod.classify(score, done, total_chk, last_d, today, dead_days)
+
+    # Staleness clock (#164): a partial plan whose declared manifest files have
+    # gone cold = "started executing, then drifted off." Key off the manifest
+    # files' commit date, NOT the plan doc's git date — plan docs are gitignored,
+    # so the doc date is null and would make this a silent no-op.
+    manifest_dt = None
+    stalled = False
+    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 manifest_dt is None:
+                stalled = True  # present on disk but never committed
+            else:
+                stalled = (today - manifest_dt.date()).days >= stall_days
+        # else: no declared files on disk yet -> brand-new, not stalled.
+
+    lie_gap = (v.label == "shipped" and total_chk > 0
+               and done / total_chk < 0.25)
     return {
         "rel": doc.rel, "kind": doc.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,
         "last_touched": last_d.isoformat() if last_d else None,
+        "manifest_last_touched": manifest_dt.date().isoformat() if manifest_dt else None,
+        "stalled": stalled,
+        "lie_gap": lie_gap,
+        "unchecked_items": manifest.unchecked_checkbox_labels(text),
+        "stall_days": stall_days,
     }
 
 
@@ -62,11 +132,7 @@ def _render(rows, repo_root) -> None:
     by = {}
     for r in rows:
         by.setdefault(r["verdict"], []).append(r)
-    lie_gap = sum(
-        1 for r in rows
-        if r["verdict"] == "shipped" and r["checkboxes_total"]
-        and r["checkboxes_done"] / r["checkboxes_total"] < 0.25
-    )
+    lie_gap = sum(1 for r in rows if r["lie_gap"])
     summary = " · ".join(f"{len(by[k])} {k}" for k in _ORDER if by.get(k))
     print(f"{len(rows)} docs · {summary}")
     print(f"lie-gap (shipped but <25% boxes checked): {lie_gap}\n")
@@ -271,7 +337,8 @@ def run(args: list) -> int:
     if type_filter and type_filter is not True:
         docs = [d for d in docs if d.kind == type_filter]
 
-    rows = [_evaluate(d, repo_root, today, dead_days) for d in docs]
+    stall_days = _resolve_stall_days(flags)
+    rows = [_evaluate(d, repo_root, today, dead_days, stall_days) for d in docs]
 
     if flags.get("--llm"):
         if flags.get("--apply"):

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

@@ -41,6 +41,20 @@ from lib.write_guard import needs_confirm
 PER_TRACK_TIMEOUT = 15  # seconds; each gh call gets this budget
 
 
+def _track_key(track) -> tuple:
+    """Stable, unique identity for a track across a reconcile run.
+
+    Track slugs are NOT unique — the same slug can name a track in two different
+    repos (this is explicitly supported). Keying reconcile's in-flight state by
+    slug let a later repo's fetch overwrite an earlier same-slug track's, so
+    under `--all --yes` issues from one repo could be written into the
+    same-named track in ANOTHER repo — cross-repo membership corruption (#255).
+    The (repo, path) pair is unique per track file and stable for the whole run.
+    Display still uses `track.name`; only dict keys use this.
+    """
+    return (track.repo, str(track.path))
+
+
 def _resolve_labels(track) -> list[str]:
     """Return the GitHub label(s) marking issues as belonging to this track.
 
@@ -143,7 +157,7 @@ def run(args: list[str]) -> int:
 
     # Phase 1: parallel fetch of labeled issues for all tracks
     work_items = [(track, _resolve_labels(track)) for track in targets if track.repo]
-    results: dict = {}  # track.name → list[dict] or None (timeout/error)
+    results: dict = {}  # _track_key(track) → list[dict] or None (timeout/error)
 
     total = len(work_items)
     if total > 1:
@@ -156,21 +170,21 @@ def run(args: list[str]) -> int:
             # Iterate in submit order for readable output; futures run in parallel
             for i, track, future in submitted:
                 try:
-                    results[track.name] = future.result()
-                    print(f"  [{i}/{total}] ✓ {track.name}")
+                    results[_track_key(track)] = future.result()
+                    print(f"  [{i}/{total}] ✓ {track.name} ({track.repo})")
                 except RuntimeError as e:
-                    print(f"  [{i}/{total}] ⚠ {track.name}: {e} — skipping")
-                    results[track.name] = None
+                    print(f"  [{i}/{total}] ⚠ {track.name} ({track.repo}): {e} — skipping")
+                    results[_track_key(track)] = None
     else:
         # Single track: fetch directly (no thread overhead)
         for i, (track, labels) in enumerate(work_items, 1):
             print(f"  [{i}/{total}] fetching {track.repo} ({track.name})...", flush=True)
             try:
-                results[track.name] = _fetch_labeled_issues(track.repo, labels)
-                print(f"  [{i}/{total}] ✓ {track.name}")
+                results[_track_key(track)] = _fetch_labeled_issues(track.repo, labels)
+                print(f"  [{i}/{total}] ✓ {track.name} ({track.repo})")
             except RuntimeError as e:
-                print(f"  [{i}/{total}] ⚠ {track.name}: {e} — skipping")
-                results[track.name] = None
+                print(f"  [{i}/{total}] ⚠ {track.name} ({track.repo}): {e} — skipping")
+                results[_track_key(track)] = None
 
     # Phase 2a: index which fetched track(s) label each issue. Used to turn a
     # bare FLAG (in a track's frontmatter, but it has lost that track's label)
@@ -178,45 +192,46 @@ def run(args: list[str]) -> int:
     # track in the same repo.
     labeled_index: dict = {}  # issue number -> list[track]
     for track in targets:
-        if not track.repo or results.get(track.name) is None:
+        if not track.repo or results.get(_track_key(track)) is None:
             continue
-        for num in {i["number"] for i in results[track.name]}:
+        for num in {i["number"] for i in results[_track_key(track)]}:
             labeled_index.setdefault(num, []).append(track)
 
     # Phase 2b: detect cross-track moves (#163). An issue qualifies when it is
     # in track A's frontmatter, no longer carries A's label, and is now labeled
     # by exactly one OTHER active track B in the same repo. Ambiguous cases
     # (two or more candidate targets) stay as plain FLAGs.
-    moved_out: dict = {}  # src track name -> set(num)
-    moved_in: dict = {}   # dst track name -> set(num)
-    move_dst: dict = {}   # (src track name, num) -> dst track
+    moved_out: dict = {}  # _track_key(src) -> set(num)
+    moved_in: dict = {}   # _track_key(dst) -> set(num)
+    move_dst: dict = {}   # (_track_key(src), num) -> dst track
     for track in targets:
-        if not track.repo or results.get(track.name) is None:
+        if not track.repo or results.get(_track_key(track)) is None:
             continue
-        labeled_nums = {i["number"] for i in results[track.name]}
+        labeled_nums = {i["number"] for i in results[_track_key(track)]}
         listed_nums = set(track.meta.get("github", {}).get("issues") or [])
         for num in sorted(listed_nums - labeled_nums):
             cands = [b for b in labeled_index.get(num, [])
                      if b is not track and b.repo == track.repo]
             if len(cands) == 1:
                 dst = cands[0]
-                moved_out.setdefault(track.name, set()).add(num)
-                moved_in.setdefault(dst.name, set()).add(num)
-                move_dst[(track.name, num)] = dst
+                moved_out.setdefault(_track_key(track), set()).add(num)
+                moved_in.setdefault(_track_key(dst), set()).add(num)
+                move_dst[(_track_key(track), num)] = dst
 
     # Phase 2c: per-track diff, report, confirm. Membership changes accumulate
-    # in `final` (track name -> desired issue set); each affected track is
+    # in `final` (_track_key -> desired issue set); each affected track is
     # written exactly ONCE at the end, so a move that touches two tracks never
     # double-writes or clobbers a sibling's accepted ADDs. A move is governed by
     # the confirmation on its SOURCE track (where the issue currently lives).
-    final: dict = {}     # track name -> set(num)
-    affected: dict = {}  # track name -> track (only those we may write)
+    final: dict = {}     # _track_key(track) -> set(num)
+    affected: dict = {}  # _track_key(track) -> track (only those we may write)
 
     def _final_for(t):
-        if t.name not in final:
-            final[t.name] = set(t.meta.get("github", {}).get("issues") or [])
-            affected[t.name] = t
-        return final[t.name]
+        key = _track_key(t)
+        if key not in final:
+            final[key] = set(t.meta.get("github", {}).get("issues") or [])
+            affected[key] = t
+        return final[key]
 
     any_changes = False
     for track in targets:
@@ -224,19 +239,19 @@ def run(args: list[str]) -> int:
         if not track.repo:
             continue
 
-        labeled = results.get(track.name)
+        labeled = results.get(_track_key(track))
         if labeled is None:
             continue
 
         labels = _resolve_labels(track)
         labeled_nums = {i["number"] for i in labeled}
         listed_nums = set(track.meta.get("github", {}).get("issues") or [])
-        out_moves = sorted(moved_out.get(track.name, set()))
+        out_moves = sorted(moved_out.get(_track_key(track), set()))
 
         # MOVE issues are reported (and applied) as moves, not as ADD on the
         # destination or FLAG on the source.
-        adds = sorted(labeled_nums - listed_nums - moved_in.get(track.name, set()))
-        flag_nums = sorted(listed_nums - labeled_nums - moved_out.get(track.name, set()))
+        adds = sorted(labeled_nums - listed_nums - moved_in.get(_track_key(track), set()))
+        flag_nums = sorted(listed_nums - labeled_nums - moved_out.get(_track_key(track), set()))
 
         if not adds and not flag_nums and not out_moves:
             continue
@@ -253,7 +268,7 @@ def run(args: list[str]) -> int:
         if out_moves:
             print(f"  MOVE ({len(out_moves)}) — relabeled to another track in this repo:")
             for num in out_moves:
-                dst = move_dst[(track.name, num)]
+                dst = move_dst[(_track_key(track), num)]
                 dst_slug = dst.meta.get("track", dst.name)
                 pub = " [dst PUBLIC]" if needs_confirm(dst.repo, cfg) else ""
                 print(f"    #{num}  {slug} → {dst_slug}{pub}")
@@ -286,7 +301,7 @@ def run(args: list[str]) -> int:
         if adds:
             _final_for(track).update(adds)
         for num in out_moves:
-            dst = move_dst[(track.name, num)]
+            dst = move_dst[(_track_key(track), num)]
             # Public-repo guard (#163): under --yes we never silently write
             # membership into a PUBLIC/shared destination track — that move is
             # skipped with a pointer to the gated `move` verb. Interactive runs
@@ -300,8 +315,8 @@ def run(args: list[str]) -> int:
             _final_for(dst).add(num)
 
     # Write each affected track exactly once, only if its set actually changed.
-    for name, issues in final.items():
-        track = affected[name]
+    for key, issues in final.items():
+        track = affected[key]
         original = set(track.meta.get("github", {}).get("issues") or [])
         if issues == original:
             continue

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

@@ -65,8 +65,17 @@ def run(args: list[str]) -> int:
 
 def _refresh_many(tracks: list, yes: bool) -> int:
     """Refresh one or more tracks. Computes proposed updates, then asks one
-    confirmation (or applies all if --yes)."""
+    confirmation (or applies all if --yes).
+
+    A track whose live fetch comes back incomplete (GitHub timeout, permission
+    error, or a frontmatter issue that no longer resolves) is SKIPPED, not
+    refreshed: the canonical table is rebuilt from frontmatter membership, so a
+    missing issue would render as '(not fetched)' and silently overwrite its
+    valid last-known row (#256). Skipped tracks are reported and force a nonzero
+    exit so `--yes` / `hygiene` callers can tell a degraded run from a clean one.
+    """
     pending = []
+    degraded = []  # (track, missing_nums) — fetch was incomplete; left untouched
     for i, track in enumerate(tracks, 1):
         print(f"  [{i}/{len(tracks)}] {track.path.name}...", flush=True)
         canonical = find_canonical_status_tables(track.body)
@@ -94,6 +103,22 @@ def _refresh_many(tracks: list, yes: bool) -> int:
         issues_by_num = {i["number"]: i for i in issues}
         state_by_num = {i["number"]: state_to_status_label(i.get("state")) for i in issues}
 
+        # Both render paths rebuild the table from frontmatter membership, so a
+        # frontmatter issue we couldn't fetch would land as a '(not fetched)'
+        # row, replacing its valid last-known values. Refuse to publish that:
+        # skip the track and surface the gap (#256). Table-only numbers that
+        # aren't in frontmatter don't feed the rebuild, so they don't gate.
+        unique_fm = set(frontmatter_nums)
+        missing = sorted(n for n in unique_fm if n not in issues_by_num)
+        if missing:
+            degraded.append((track, missing))
+            scope = ("no issues" if len(missing) == len(unique_fm)
+                     else f"{len(missing)}/{len(unique_fm)} issues")
+            nums = ", ".join(f"#{n}" for n in missing)
+            print(f"      ⚠ fetch returned {scope} short ({nums}) "
+                  f"— skipping to preserve current rows")
+            continue
+
         if canonical:
             # Canonical table → RE-DERIVE the whole block from frontmatter
             # membership + live data, milestone-ordered (#101). Re-deriving from
@@ -113,6 +138,9 @@ def _refresh_many(tracks: list, yes: bool) -> int:
         pending.append((track, new_body, detail))
 
     if not pending:
+        if degraded:
+            _report_degraded(degraded)
+            return 1
         print("All tracks in sync.")
         return 0
 
@@ -127,9 +155,29 @@ def _refresh_many(tracks: list, yes: bool) -> int:
     for track, new_body, _ in pending:
         write_file(track.path, track.meta, new_body)
     print(f"\n✓ Updated {len(pending)} file(s).")
+
+    if degraded:
+        _report_degraded(degraded)
+        return 1
     return 0
 
 
+def _report_degraded(degraded: list) -> None:
+    """Summarize tracks skipped because their live fetch was incomplete (#256).
+
+    Their tables are left exactly as they were — better a stale-but-valid row
+    than a '(not fetched)' placeholder published as truth. A persistently
+    missing number usually means the issue was deleted/transferred and should
+    be dropped from frontmatter."""
+    print(f"\n⚠ Skipped {len(degraded)} track(s) — live fetch was incomplete, "
+          f"so their tables were left untouched:")
+    for track, missing in degraded:
+        nums = ", ".join(f"#{n}" for n in missing)
+        print(f"    {track.path.name}: could not fetch {nums}")
+    print("  Re-run once GitHub is reachable, or drop deleted issues from "
+          "frontmatter (`/work-plan reconcile`).")
+
+
 def _rederive_canonical(track, canonical_tables, frontmatter_nums,
                         issues_by_num, state_by_num):
     """Rebuild the canonical block, milestone-ordered, from live data.