@stylusnexus/work-plan 2026.6.11 → 2026.6.13-2

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

@@ -11,6 +11,7 @@ from pathlib import Path
 
 from lib import config as config_mod
 from lib import doc_discovery, manifest, git_state, github_state
+from lib import frontmatter
 from lib import verdict as verdict_mod
 from lib import status_header
 from lib import llm_evidence
@@ -19,9 +20,45 @@ 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"]
 
+# Human verdict-override (#286): a reviewer affirms the verdict in the doc's
+# YAML frontmatter, so the mechanical heuristic (file score + checkbox %) stops
+# second-guessing it — and the "shipped but boxes unchecked" lie-gap goes quiet.
+_OVERRIDE_VERDICTS = {"shipped", "partial", "dead"}
+_OVERRIDE_GLYPH = {"shipped": "✅", "partial": "🟡", "dead": "💀"}
+
+
+def _read_fm_signals(path) -> tuple:
+    """Read the frontmatter signals plan-status honors (#286), in ONE parse:
+
+        (override, acknowledged, baseline)
+
+    `override` is the `verdict_override` value (case-insensitive shipped|partial|
+    dead, else None — a typo can't pin a bogus verdict). `acknowledged` is True
+    when the doc carries a truthy `acknowledged` (the durable ack plan-ack writes).
+    `baseline` is the `verdict_baseline` value (a verdict string, else None) that
+    plan-baseline stamps for drift detection. All frontmatter-only — never the
+    body/checkboxes. A doc with no frontmatter (most plans) parses to empty meta,
+    a clean (None, False, None) no-op."""
+    try:
+        meta, _ = frontmatter.parse_file(Path(path))
+    except Exception:
+        return (None, False, None)
+    if not isinstance(meta, dict):
+        return (None, False, None)
+    val = meta.get("verdict_override")
+    override = (val.strip().lower()
+                if isinstance(val, str) and val.strip().lower() in _OVERRIDE_VERDICTS
+                else None)
+    acknowledged = bool(meta.get("acknowledged"))
+    bval = meta.get("verdict_baseline")
+    baseline = (bval.strip().lower()
+                if isinstance(bval, str) and bval.strip().lower() in _OVERRIDE_VERDICTS
+                else None)
+    return (override, acknowledged, baseline)
+
 
 def _resolve_repo_root(flags) -> Path:
     repo = flags.get("--repo")
@@ -35,8 +72,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,25 +131,72 @@ 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)
+
+    # Frontmatter signals (#286): a `verdict_override` pins the verdict over the
+    # mechanical one (applied BEFORE the staleness clock + lie-gap so both key off
+    # the confirmed verdict), and `acknowledged` is the durable, shared ack.
+    override, acknowledged, baseline = _read_fm_signals(doc.path)
+    if override:
+        v = verdict_mod.Verdict(
+            override, _OVERRIDE_GLYPH[override], f"human-confirmed · {v.rationale}")
+
+    # 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.
+
+    # A human-confirmed verdict silences the lie-gap: the reviewer has affirmed
+    # the "shipped" claim despite unchecked boxes, so it's no longer a lie.
+    lie_gap = (not override and v.label == "shipped" and total_chk > 0
+               and done / total_chk < 0.25)
+    # Drift (#286): a stamped `verdict_baseline` that no longer matches the live
+    # verdict — e.g. a once-shipped plan whose declared files were deleted. A
+    # human override owns the verdict, so it suppresses drift (same as lie-gap).
+    verdict_drift = bool(baseline) and not override and baseline != v.label
     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,
+        "override": override,
+        "acknowledged": acknowledged,
+        "verdict_baseline": baseline,
+        "verdict_drift": verdict_drift,
+        "offtree_paths": manifest.offtree_declared_paths(decls, repo_root),
+        "unchecked_items": manifest.unchecked_checkbox_labels(text),
+        "stall_days": stall_days,
     }
 
 
+# Public alias so other commands (e.g. `export`, which resolves a track's linked
+# plan badge for #285) reuse the SAME verdict/lie-gap/override evaluation instead
+# of reimplementing it and drifting. Kept at this module path so the existing
+# tests that patch `commands.plan_status.git_state.*` and call `_evaluate`
+# directly keep working unchanged.
+evaluate_doc = _evaluate
+
+
 def _render(rows, repo_root) -> None:
     print(f"# plan-status — {repo_root}\n")
     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 +401,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/push_track.py

@@ -0,0 +1,156 @@
+"""push-track — promote a PRIVATE track to a repo's SHARED tier and publish it
+(#306).
+
+Tracks default to the private tier (`notes_root`, local-only, never pushed). The
+shared tier lives in a repo's `.work-plan/` on its canonical `plan_branch` (via a
+git worktree) and is how a track becomes visible to teammates. This verb moves a
+private track's `.md` into the shared `.work-plan/`, removes the private copy
+(so the track isn't duplicated), commits it to the plan branch, and pushes —
+unless `--no-push`.
+
+The tier is derived from WHERE the file lives, so promotion is a file move; no
+frontmatter edit. Pushing to a PUBLIC repo's plan branch makes the plan
+world-visible — the exposed state the viewer's visibility×tier badge warns about
+— so the push is confirm-token gated, like `plan-branch push`.
+
+Usage:
+    work_plan.py push-track <track | track@repo> [--repo=<key>] [--no-push] [--confirm=<token>]
+"""
+import json
+import sys
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import (
+    discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError,
+)
+from lib.frontmatter import write_file
+from lib import plan_worktree as pw
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+KNOWN = {"--repo", "--no-push", "--confirm"}
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+    if not positional:
+        print("usage: work_plan.py push-track <track> [--repo=<key>] [--no-push] "
+              "[--confirm=<token>]", file=sys.stderr)
+        return 2
+    name_from_arg, repo_from_arg = parse_track_repo_arg(positional[0])
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    repo_qualifier = repo_from_arg or repo_flag
+    no_push = bool(flags.get("--no-push"))
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    try:
+        track = find_track_by_name(name_from_arg, discover_tracks(cfg), repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    if not track:
+        print(f"No track matching '{name_from_arg}'.", file=sys.stderr)
+        return 1
+    if track.tier == "shared":
+        print(f"'{track.name}' is already in the shared tier — nothing to promote.",
+              file=sys.stderr)
+        return 1
+    if not track.folder:
+        print(f"'{track.name}' has no configured repo (folder) — can't resolve a "
+              "shared tier to promote into.", file=sys.stderr)
+        return 1
+
+    entry = (cfg.get("repos") or {}).get(track.folder) or {}
+    github = entry.get("github")
+    branch = entry.get("plan_branch")
+    local = entry.get("local")
+    if not local:
+        print(f"repo '{track.folder}' has no local clone path in config.", file=sys.stderr)
+        return 2
+    if not branch:
+        print(f"repo '{track.folder}' has no shared plan branch. Set one up first:\n"
+              f"  /work-plan plan-branch init {track.folder}", file=sys.stderr)
+        return 1
+
+    # Exposure gate (the push is what publishes). Fire BEFORE any mutation so the
+    # viewer's modal lands first; --no-push keeps it local, so no gate. Fails
+    # CLOSED on unknown visibility (same as plan-branch push).
+    if not no_push and needs_confirm(github, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, github, track.name)):
+            print(_needs_confirm_json(github, branch, track.name))
+            return 0
+
+    # Resolve (and ensure) the shared-tier worktree dir.
+    shared_dir = pw.shared_tier_dir(entry)
+    if shared_dir is None:
+        print(f"ERROR: could not open the shared plan branch '{branch}' for "
+              f"'{track.folder}'. Run `plan-branch init {track.folder}` first.",
+              file=sys.stderr)
+        return 1
+    dest = shared_dir / f"{track.name}.md"
+    if dest.exists():
+        print(f"ERROR: a shared track '{track.name}' already exists at {dest}.",
+              file=sys.stderr)
+        return 1
+
+    # Move: write into the shared tier (frontmatter preserved), then remove the
+    # private copy so discover_tracks shows the track once (shared), not twice.
+    write_file(dest, track.meta, track.body)
+    try:
+        track.path.unlink()
+    except OSError as e:
+        print(f"WARN: wrote the shared copy but could not remove the private "
+              f"file {track.path}: {e} — remove it by hand to avoid a duplicate.",
+              file=sys.stderr)
+
+    worktree = shared_dir.parent
+    sha = pw.commit_shared_tier(
+        worktree, f"work-plan: promote track '{track.name}' to shared tier",
+        [f".work-plan/{track.name}.md"],
+    )
+    if sha is None:
+        print(f"WARN: moved '{track.name}' into the shared tier but the commit "
+              "did not land — commit it by hand in the plan-branch worktree.",
+              file=sys.stderr)
+
+    if no_push:
+        print(f"✓ promoted '{track.name}' to the shared tier (local commit "
+              f"{sha or '—'}). Run `plan-branch push {track.folder}` to share it.")
+        return 0
+
+    proc = pw.push_plan_branch(Path(local).expanduser(), branch)
+    if proc is None or proc.returncode != 0:
+        err = (getattr(proc, "stderr", "") or "").strip()
+        if "protected" in err.lower() or "pull request" in err.lower():
+            print(f"ERROR: origin rejected the push — '{branch}' looks protected. "
+                  f"Exempt the plan branch from PR/branch-protection, or push it "
+                  "by hand once. The promotion is committed locally.", file=sys.stderr)
+        else:
+            print(f"ERROR: promoted + committed locally, but the push failed: "
+                  f"{err or 'unknown git error'}. Retry with `plan-branch push "
+                  f"{track.folder}`.", file=sys.stderr)
+        return 1
+    print(f"✓ promoted '{track.name}' to the shared tier and pushed '{branch}'. "
+          "Teammates can `plan-branch init` to see it.")
+    return 0
+
+
+def _needs_confirm_json(github, branch, name) -> str:
+    return json.dumps({
+        "needs_confirm": True,
+        "reason": (
+            f"{github} is PUBLIC (or its visibility is unknown). Promoting "
+            f"'{name}' to the shared tier and pushing '{branch}' makes that "
+            "track — its issue notes, priorities, and planning text — visible to "
+            "anyone on the internet, and it stays in public git history even if "
+            "later removed. Use --no-push to keep it local for now."
+        ),
+        "token": make_token(github, name),
+    })

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.