@stylusnexus/work-plan 2026.7.13 → 2026.7.16

package/README.md

@@ -54,6 +54,7 @@ The five essentials you'll use 80% of the time are:
 | `/work-plan reconcile <track> \| --all \| --repo=<key> [--draft] [--yes]` | Track frontmatter membership drifted from GitHub labels. Use on label-driven tracks only — for hand-curated tracks, use `refresh-md` instead. In an `--all`/`--repo` sweep it also moves issues relabeled from one track to another in the same repo. `--draft` previews proposed ADDs/MOVEs/FLAGs; `--yes` applies without prompting. `--repo=<key>` scopes the sweep to one repo. |
 | `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Runs four steps: ① `refresh-md --all` (pull live GitHub state into every active track's status table), ② `reconcile --all` (sync frontmatter membership against GitHub labels), ③ `dedupe-tiers` (report shared/private duplicate tracks, no deletes), ④ `duplicates` (flag likely-duplicate issues). `--repo=<key>` scopes steps ①–③ to one repo; step ④ is skipped in scoped mode. |
 | `/work-plan in-progress <n> [--clear]` | Starting or stopping active work on an issue. Adds (or removes with `--clear`) the `work-plan:in-progress` label on GitHub. Repo-resolved from the issue number, or pass `--repo=<key\|slug>` to disambiguate. `brief`/`orient`/the VS Code viewer also detect in-progress automatically from a hot `feat/<n>-`/`fix/<n>-` branch. |
+| `/work-plan doctor --fix` | Detect config drift after a folder rename or GitHub repo move. Checks whether config.yml, local clones, track frontmatter, and GitHub match (renamed local folder, renamed repo, broken path, duplicate entries, stale per-track `github.repo`). `--fix` corrects the two safe cases (GitHub-confirmed rename, stale track slug) and re-scans. |
 
 A dozen more subcommands cover slotting new issues into tracks, closing tracks (shipped/abandoned/parked), and one-time priority-label backfill. Three capabilities worth calling out explicitly:
 
@@ -529,6 +530,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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. 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` + `dedupe-tiers` (report-only) + `duplicates`. With `--repo=<key>`, steps 1–3 scope to that repo and the global `duplicates` step is skipped. |
+| `doctor [--json] [--fix]` | Detect config drift: a renamed local folder or GitHub repo that `config.yml` no longer matches, a non-git local path, duplicate entries, an invalid/missing `notes_root`, an orphaned notes folder, or a stale per-track `github.repo`. Run this right after any rename/move. `--fix` corrects only the two mechanically-safe cases (a GitHub-confirmed rename, a stale track slug) and always re-scans afterward. `--json` for machine output. |
 | `dedupe-tiers [--repo=<key>] [--apply]` | Remove private track copies that a shared twin in a repo's `.work-plan/` supersedes (#359). When a track is promoted to the shared tier, its private original under `notes_root` is sometimes left behind (bulk/manual promotion, or a failed unlink during `push-track`) — `discover_tracks` then warns `exists in both shared and private` on every run with no cleanup path. This removes the safe orphans and **refuses** any whose private copy references issue numbers the shared one lacks (no silent data loss; the invariant is `issue_refs(private) ⊆ issue_refs(shared)`). Covers active and archived tiers. Default is a **dry-run report**; `--apply` deletes (auto-committed to `notes_root`, so undoable via `notes-vcs undo`). `--repo=<key>` scopes to one repo. |
 | `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. |

package/VERSION

@@ -1 +1 @@
-2026.07.13+6341563
+2026.07.16+bcb403e

package/package.json

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

@@ -17,6 +17,7 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan handoff [track] [--auto-next \| --set-next 1,2,3]` | Wrapping up a work block. Captures touched + next + blockers; writes session log. Add `--auto-next` to suggest a priority-sorted next_up list from open issues (interactive: apply / edit / skip). Tracks with `next_up_auto: true` in frontmatter get the auto-derived list surfaced in `brief` automatically. |
 | `/work-plan orient [track]` (alias `where-was-i`) | Re-orienting. With a track: ~15-line track paste-block. Without: cwd snapshot (branch, recent commits, modified files) for non-track work. Add `--pick` for the interactive track picker. |
 | `/work-plan hygiene [--repo=<key>]` | **Weekly all-in-one cleanup.** Three steps in sequence: ① `refresh-md --all` — pull live GitHub state into every active track's status table (same as "Sync Issue States from GitHub" but for all tracks); ② `reconcile --all` — sync track frontmatter membership against GitHub labels; ③ `duplicates` — flag likely-duplicate issues for consolidation. Run once a week to keep status icons, labels, and dedup state honest. `--repo=<key>` scopes steps ① and ② to one repo; step ③ is skipped in scoped mode (it needs a single explicit repo to be unambiguous). |
+| `/work-plan doctor [--json] [--fix]` | Config drifted — a renamed local folder or GitHub repo, config.yml no longer matches. Run right after any rename/move. `--fix` corrects the safe subset and re-scans. |
 | `/work-plan slot <issue-num> [track]` | A new GitHub issue should belong to a track. If the issue is already listed in another active track's frontmatter, you'll be prompted to move it (remove from source) instead of duplicating. |
 | `/work-plan close [track]` | Track is done (shipped) / paused (parked) / won't ship (abandoned). |
 | `/work-plan mark-cleanup <track> [--reason=<text>] [--clear]` | Earmark a track for cleanup — a reversible `cleanup_candidate` flag `hygiene` surfaces. Triggers: "mark this track for cleanup / retirement". Non-destructive. |

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

@@ -1,4 +1,6 @@
 """brief subcommand — fully featured."""
+from __future__ import annotations
+
 import os
 from datetime import datetime
 from pathlib import Path
@@ -108,9 +110,43 @@ def run(args: list[str]) -> int:
     print(framing)
     print()
 
+    # Batch same-repo GitHub reads across tracks (#420): tracks sharing a repo
+    # otherwise each re-fetch the same issue set / recent-issues list from
+    # scratch. Fetch once per repo here, then partition back into each track
+    # in _build_track_block — field coverage, ordering, and fail-soft fallback
+    # stay identical to the old per-track fetch (same underlying helpers, same
+    # per-track number/slug subsets, just fetched once instead of N times).
+    repo_tracks: dict = {}
+    for t in active:
+        if t.repo:
+            repo_tracks.setdefault(t.repo, []).append(t)
+
+    issues_by_repo: dict = {}
+    new_issues_by_repo: dict = {}
+    for repo, rtracks in repo_tracks.items():
+        all_nums = _numeric_refs(*[
+            ref_list
+            for rt in rtracks
+            for ref_list in (rt.meta.get("github", {}).get("issues") or [],
+                             rt.meta.get("next_up") or [])
+        ])
+        issues_by_repo[repo] = (
+            {i["number"]: i for i in fetch_issues(repo, all_nums)} if all_nums else {}
+        )
+
+        slugs = [rt.meta.get("track", rt.name) for rt in rtracks]
+        slug_labels = build_slug_labels(rtracks)
+        new_issues_by_repo[repo] = find_new_issues_for_tracks(
+            repo, slugs, slug_labels=slug_labels, since_days=7,
+        )
+
     blocks = []
     for t in active:
-        b = _build_track_block(t, cfg, now)
+        b = _build_track_block(
+            t, cfg, now,
+            repo_issues_by_num=issues_by_repo.get(t.repo, {}),
+            repo_new_issues=new_issues_by_repo.get(t.repo, {}),
+        )
         blocks.append((b["sort_key"], b))
 
     blocks.sort(key=lambda x: x[0])
@@ -142,10 +178,14 @@ def run(args: list[str]) -> int:
     return 0
 
 
-def _build_track_block(track, cfg, now: datetime) -> dict:
+def _build_track_block(track, cfg, now: datetime, *,
+                       repo_issues_by_num: dict | None = None,
+                       repo_new_issues: dict | None = None) -> dict:
     meta = track.meta
     repo = track.repo
     local = track.local_path
+    repo_issues_by_num = repo_issues_by_num or {}
+    repo_new_issues = repo_new_issues or {}
 
     issue_nums = meta.get("github", {}).get("issues") or []
     stored_next_up = meta.get("next_up") or []
@@ -153,7 +193,9 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
     # so stale closed entries surface as a clear signal rather than vanishing.
     # Only numeric refs are fetchable; string tokens in next_up are dropped (#417).
     fetch_nums = _numeric_refs(issue_nums, stored_next_up)
-    issues = fetch_issues(repo, fetch_nums) if (repo and fetch_nums) else []
+    # Partition this track's slice out of the repo-batched fetch (#420) instead
+    # of fetching it directly — same order, same skip-if-missing fallback.
+    issues = [repo_issues_by_num[n] for n in fetch_nums if n in repo_issues_by_num]
     issues_by_num = {i["number"]: i for i in issues}
 
     # When `next_up_auto: true` is set in track frontmatter, derive the list
@@ -225,18 +267,16 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
         operational_status = stored_status
 
     track_slug = meta.get("track", track.name)
-    slug_labels = build_slug_labels([track])
-    new_issues_map = find_new_issues_for_tracks(repo, [track_slug], slug_labels=slug_labels, since_days=7) if repo else {}
     listed_set = set(issue_nums)
     new_issues = []
-    for issue in new_issues_map.get(track_slug, []):
+    for issue in repo_new_issues.get(track_slug, []):
         if issue["number"] in listed_set:
             continue
         new_issues.append({"number": issue["number"], "title": issue["title"]})
 
     drift_items = detect_drift(track.body, issues) if issues else []
 
-    related_recent_count = len(new_issues_map.get(track_slug, []))
+    related_recent_count = len(repo_new_issues.get(track_slug, []))
     signals = compute_signals(meta, issues, local, related_recent_count)
     closure_ready, _ = is_closure_ready(signals)
     if closure_ready:

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

@@ -0,0 +1,529 @@
+"""doctor subcommand — detect (and, for a safe subset, fix) drift between
+config.yml, local git clones, GitHub, and notes_root track frontmatter.
+
+See docs/superpowers/specs/2026-07-15-config-drift-doctor-design.md (revision
+5) for the full design and the four Codex /spec-review passes that shaped it.
+Read-only by default; --fix applies the two mechanically-safe corrections
+(a GitHub-confirmed rename, a stale track frontmatter slug) and always
+re-scans from disk afterward before deciding the exit code.
+"""
+import json
+import re
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor, wait
+from pathlib import Path
+
+from lib.config import (
+    load_config, ConfigError, is_valid_git_repo,
+    DEFAULT_CONFIG_PATH, write_repo_field, notes_vcs_auto_commit,
+)
+from lib.cwd_repo import _git, _normalize_remote_url
+from lib.frontmatter import parse_file, write_file
+from lib.github_state import repo_full_name
+from lib.notes_vcs import dirty_paths_checked, auto_commit
+from lib.prompts import parse_flags
+from lib.tracks import iter_private_track_paths
+
+_FATAL_EXCEPTIONS = (
+    ConfigError,
+    FileNotFoundError,
+    subprocess.CalledProcessError,
+    json.JSONDecodeError,
+    OSError,
+    AttributeError,
+    UnicodeDecodeError,
+)
+
+SAFE_KEY_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+SCAN_DEADLINE = 60  # seconds, wall-clock budget for Step 1 regardless of repo count
+MAX_GH_WORKERS = 4
+
+_HOST_RE = re.compile(r"^[\w.+-]+@([\w.-]+):|^[\w.+-]+://(?:[^/@]+@)?([^/]+)/")
+
+
+def _remote_host(url: str) -> "str | None":
+    """Extract the host from a git remote URL, preserving it (unlike
+    `_normalize_remote_url`, which discards the host on purpose for its own
+    slug-comparison use case). Handles the same two forms `_normalize_remote_url`
+    does: scp-like and scheme://. An explicit `:<port>` on the scheme form
+    (e.g. `https://github.com:8080/org/repo.git`) is stripped so a genuine
+    github.com remote isn't misreported as non-GitHub just because it names a
+    port; the scp-like form's captured group can never contain a colon (its
+    own colon is the path separator, outside the capture), so the split is a
+    no-op there. Returns None if unparseable."""
+    if not url:
+        return None
+    m = _HOST_RE.match(url.strip())
+    if not m:
+        return None
+    host = (m.group(1) or m.group(2) or "").lower()
+    return host.split(":", 1)[0] or None
+
+
+def _finding(type_, *, key=None, folder=None, track=None, message,
+             fixable=False, unverified=False, old=None, new=None):
+    return {
+        "type": type_, "key": key, "folder": folder, "track": track,
+        "message": message, "fixable": fixable, "unverified": unverified,
+        "old": old, "new": new,
+    }
+
+
+def _load_config_safely():
+    """Returns (cfg, fatal_message) — exactly one is None."""
+    try:
+        return load_config(), None
+    except _FATAL_EXCEPTIONS as e:
+        return None, str(e)
+
+
+def _validate_repo_field_shapes(cfg):
+    """Excludes any `repos` entry whose github/local field has the wrong type,
+    reporting `repo_entry_malformed` for each. Returns (valid_repos, findings)
+    — valid_repos is a NEW dict, cfg["repos"] is left untouched.
+    """
+    valid = {}
+    findings = []
+    for key, entry in (cfg.get("repos") or {}).items():
+        github = entry.get("github")
+        local = entry.get("local")
+        if not isinstance(github, str):
+            findings.append(_finding(
+                "repo_entry_malformed", key=key,
+                message=f"'github' must be a string, got {type(github).__name__}",
+            ))
+            continue
+        if local is not None and not isinstance(local, str):
+            findings.append(_finding(
+                "repo_entry_malformed", key=key,
+                message=f"'local' must be a string, got {type(local).__name__}",
+            ))
+            continue
+        valid[key] = entry
+    return valid, findings
+
+
+def _resolve_canonical_slugs(repos: dict) -> dict:
+    """Step 1: one gh-confirmed canonical slug per repo, resolved concurrently
+    with an overall wall-clock deadline so a large repo count can't stall the
+    whole scan (or the VS Code extension's activation call, which has no
+    process-level timeout of its own). Not-yet-started jobs are cancelled at
+    the deadline so this function's own return time stays bounded by roughly
+    SCAN_DEADLINE + GH_TIMEOUT regardless of repo count — already-running
+    calls (up to MAX_GH_WORKERS of them) can't be cancelled mid-subprocess,
+    but that residual is count-independent, not the defect this fixes.
+    """
+    result = {}
+    if not repos:
+        return result
+    pool = ThreadPoolExecutor(max_workers=min(MAX_GH_WORKERS, len(repos)))
+    try:
+        futures = {pool.submit(repo_full_name, entry["github"]): key
+                   for key, entry in repos.items()}
+        done, not_done = wait(futures, timeout=SCAN_DEADLINE)
+        for fut in done:
+            key = futures[fut]
+            full_name = fut.result()
+            configured = repos[key]["github"]
+            if full_name is None:
+                result[key] = {"canonical": configured, "unverified": True}
+            else:
+                result[key] = {"canonical": full_name, "unverified": False}
+        for fut in not_done:
+            key = futures[fut]
+            fut.cancel()
+            result[key] = {"canonical": repos[key]["github"], "unverified": True}
+    finally:
+        pool.shutdown(wait=False, cancel_futures=True)
+    return result
+
+
+def _step1_findings(repos: dict, canonical: dict, scalar_shape_keys=None) -> list:
+    scalar_shape_keys = scalar_shape_keys or set()
+    findings = []
+    for key, entry in repos.items():
+        configured = entry["github"]
+        info = canonical[key]
+        if info["unverified"]:
+            findings.append(_finding(
+                "github_repo_unreachable", key=key, unverified=True,
+                message=f"could not confirm GitHub identity for '{configured}' "
+                        "(404, no access, rate-limited, offline, or scan timed out)",
+            ))
+            continue
+        if info["canonical"].lower() == configured.lower():
+            continue
+        fixable = True
+        reason = None
+        if not SAFE_KEY_RE.match(key):
+            fixable = False
+            reason = "config key contains characters unsafe for automatic YAML updates"
+        elif key in scalar_shape_keys:
+            fixable = False
+            reason = (f"repo entry '{key}' uses the scalar shorthand form — convert "
+                       f"'{key}: \"{configured}\"' to '{key}: {{github: \"{configured}\"}}' "
+                       "by hand in config.yml, then re-run doctor --fix")
+        message = (f"'{key}' GitHub repo renamed: configured as '{configured}', "
+                   f"GitHub now reports '{info['canonical']}'")
+        if reason:
+            message += f" — {reason}"
+        findings.append(_finding(
+            "github_rename_detected", key=key, message=message, fixable=fixable,
+            old=configured, new=info["canonical"],
+        ))
+    return findings
+
+
+def _step2_findings(repos: dict, canonical: "dict | None" = None) -> list:
+    canonical = canonical or {}
+    findings = []
+    for key, entry in repos.items():
+        local = entry.get("local")
+        if not local:
+            continue
+        p = Path(local).expanduser()
+        if not p.is_absolute():
+            findings.append(_finding(
+                "local_path_relative", key=key,
+                message=f"'{key}'.local is a relative path ('{local}') — "
+                        "results would depend on the current working directory; "
+                        "use an absolute path",
+            ))
+            continue
+        if not p.exists():
+            findings.append(_finding(
+                "missing_local", key=key,
+                message=f"'{key}'.local ('{local}') does not exist on disk",
+            ))
+            continue
+        if not is_valid_git_repo(p):
+            findings.append(_finding(
+                "local_not_git", key=key,
+                message=f"'{key}'.local ('{local}') has no .git entry",
+            ))
+            continue
+        proc = _git(p, "remote", "get-url", "origin")
+        if proc is None or proc.returncode != 0 or not proc.stdout.strip():
+            findings.append(_finding(
+                "local_remote_missing", key=key,
+                message=f"'{key}'.local ('{local}') has no resolvable 'origin' remote",
+            ))
+            continue
+        raw_url = proc.stdout.strip()
+        host = _remote_host(raw_url)
+        if host != "github.com":
+            findings.append(_finding(
+                "local_remote_mismatch", key=key,
+                message=f"'{key}'.local's origin ('{raw_url}') is a non-GitHub host "
+                        f"({host or 'unrecognized'}) — not compared to a slug",
+            ))
+            continue
+        slug = _normalize_remote_url(raw_url)
+        info = canonical.get(key)
+        expected = info["canonical"] if info else entry["github"]
+        if slug and slug != expected.lower():
+            findings.append(_finding(
+                "local_remote_mismatch", key=key, fixable=False,
+                message=f"'{key}'.local's origin ('{slug}') differs from the "
+                        f"configured/canonical slug ('{expected}') — could be a "
+                        "legitimate fork or mirror",
+            ))
+    return findings
+
+
+def _notes_root_status(cfg: dict):
+    """Returns (walkable: bool, finding_or_None). walkable is False when either
+    notes_root_invalid or notes_root_missing fired — Step 4 must not walk."""
+    raw = cfg.get("notes_root")
+    if not isinstance(raw, str) or not raw.strip():
+        return False, _finding("notes_root_invalid",
+                                message="notes_root is blank or not a string")
+    p = Path(raw).expanduser()
+    if not p.is_absolute():
+        return False, _finding("notes_root_invalid",
+                                message=f"notes_root ('{raw}') is not an absolute path")
+    resolved = p.resolve()
+    if str(resolved) == resolved.anchor:
+        return False, _finding("notes_root_invalid",
+                                message=f"notes_root ('{raw}') resolves to a bare filesystem root")
+    if not resolved.is_dir():
+        return False, _finding("notes_root_missing",
+                                message=f"notes_root ('{raw}') does not exist or is not a directory")
+    return True, None
+
+
+def _step3_findings(repos: dict, canonical: dict, cfg: dict) -> list:
+    findings = []
+    by_local = {}
+    by_slug = {}
+    for key, entry in repos.items():
+        local = entry.get("local")
+        if local:
+            resolved = str(Path(local).expanduser().resolve())
+            by_local.setdefault(resolved, []).append(key)
+        info = canonical.get(key)
+        slug = (info["canonical"] if info else entry["github"]).lower()
+        by_slug.setdefault(slug, []).append(key)
+    for resolved, keys in by_local.items():
+        if len(keys) > 1:
+            for key in keys:
+                findings.append(_finding(
+                    "duplicate_local", key=key,
+                    message=f"'{key}' shares local path '{resolved}' with {[k for k in keys if k != key]}",
+                ))
+    for slug, keys in by_slug.items():
+        if len(keys) > 1:
+            for key in keys:
+                findings.append(_finding(
+                    "duplicate_github", key=key,
+                    message=f"'{key}' shares canonical slug '{slug}' with {[k for k in keys if k != key]}",
+                ))
+    walkable, notes_finding = _notes_root_status(cfg)
+    if notes_finding:
+        findings.append(notes_finding)
+    return findings
+
+
+def _step4_findings(cfg: dict, repos: dict, canonical: dict, walkable: bool) -> list:
+    if not walkable:
+        return []
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    findings = []
+
+    # Walk once; reuse for both the orphaned-folder pass and the per-track pass.
+    track_paths = iter_private_track_paths(notes_root, include_archive=True)
+    folders_with_tracks = {
+        p.relative_to(notes_root).parts[0]
+        for p in track_paths
+        if len(p.relative_to(notes_root).parts) > 1
+    }
+
+    for child in sorted(notes_root.iterdir()):
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        if child.name not in folders_with_tracks:
+            continue
+        if child.name not in repos:
+            findings.append(_finding(
+                "orphaned_folder", folder=child.name,
+                message=f"notes_root folder '{child.name}' has no matching repos.<key>",
+            ))
+
+    for md_path in track_paths:
+        rel = md_path.relative_to(notes_root)
+        folder = rel.parts[0] if len(rel.parts) > 1 else None
+        track_name = md_path.name
+        try:
+            meta, _body = parse_file(md_path)
+        except Exception as e:
+            findings.append(_finding(
+                "track_unreadable", folder=folder, track=track_name,
+                message=f"could not parse frontmatter: {e}",
+            ))
+            continue
+        if not isinstance(meta, dict):
+            findings.append(_finding(
+                "track_unreadable", folder=folder, track=track_name,
+                message="frontmatter root is not a mapping",
+            ))
+            continue
+        github_block = meta.get("github")
+        if github_block is None:
+            continue
+        if not isinstance(github_block, dict):
+            findings.append(_finding(
+                "track_unreadable", folder=folder, track=track_name,
+                message="frontmatter 'github' is not a mapping",
+            ))
+            continue
+        repo_value = github_block.get("repo")
+        if repo_value is None:
+            continue
+        if not isinstance(repo_value, str):
+            findings.append(_finding(
+                "track_unreadable", folder=folder, track=track_name,
+                message="frontmatter 'github.repo' is not a string",
+            ))
+            continue
+        if folder is None or folder not in repos:
+            continue
+        info = canonical.get(folder)
+        if info is None or info["unverified"]:
+            continue
+        expected = info["canonical"]
+        if repo_value.lower() != expected.lower():
+            findings.append(_finding(
+                "stale_frontmatter", folder=folder, track=track_name, fixable=True,
+                message=f"track '{track_name}' frontmatter github.repo is '{repo_value}', "
+                        f"folder '{folder}' canonical slug is '{expected}'",
+                old=repo_value, new=expected,
+            ))
+    return findings
+
+
+def _scan(cfg, repos):
+    """Steps 1-4 — the full scan pipeline. Re-run verbatim after --fix applies
+    corrections (see `run()`), so a fixed finding must actually disappear."""
+    canonical = _resolve_canonical_slugs(repos)
+    findings = _step1_findings(repos, canonical, cfg.get("_scalar_shape_keys"))
+    findings += _step2_findings(repos, canonical)
+    findings += _step3_findings(repos, canonical, cfg)
+    walkable, _ = _notes_root_status(cfg)
+    findings += _step4_findings(cfg, repos, canonical, walkable)
+    return findings
+
+
+def _apply_config_fixes(findings: list) -> list:
+    """Applies every fixable github_rename_detected finding to config.yml.
+    Returns the attempt ledger (one entry per attempt, in the order given)."""
+    ledger = []
+    for f in findings:
+        if f["type"] != "github_rename_detected" or not f["fixable"]:
+            continue
+        entry = {"type": f["type"], "key": f["key"], "folder": None, "track": None,
+                  "old": f["old"], "new": f["new"], "fixed": False, "error": None}
+        try:
+            write_repo_field(f["key"], {"github": f["new"]}, path=DEFAULT_CONFIG_PATH)
+            entry["fixed"] = True
+        except subprocess.CalledProcessError as e:
+            entry["error"] = (e.stderr or str(e)).strip()
+        ledger.append(entry)
+    return ledger
+
+
+def _apply_frontmatter_fixes(notes_root: Path, findings: list, auto_commit_enabled: bool):
+    """Applies every fixable stale_frontmatter finding, subject to the
+    dirty-file policy. Returns (ledger, skipped_due_to_unknown_dirty_state).
+
+    NOTE: a stale_frontmatter finding's `fixable=True` (set in
+    _step4_findings, at scan time) is an optimistic classification — that
+    scan has no way to know whether the track file is currently dirty. This
+    function is the authoritative, fix-time gate: it re-checks dirty state
+    via dirty_paths_checked() below before ever writing, and skips (fixable
+    in practice: false) anything already dirty or anything it can't verify.
+    A scan can therefore report a finding as "fixable" that a subsequent
+    --fix safely declines to touch. This is deliberate, not a bug.
+    """
+    ok_before, dirty_before = dirty_paths_checked(notes_root)
+    if not ok_before:
+        return [], True  # fail closed: no writes at all this run
+
+    ledger = []
+    changed_paths = []
+    for f in findings:
+        if f["type"] != "stale_frontmatter" or not f["fixable"]:
+            continue
+        rel = f"{f['folder']}/{f['track']}"
+        entry = {"type": f["type"], "key": None, "folder": f["folder"], "track": f["track"],
+                  "old": f["old"], "new": f["new"], "fixed": False, "error": None}
+        if rel in dirty_before:
+            entry["error"] = "file has uncommitted changes; commit/stash first or fix by hand"
+            ledger.append(entry)
+            continue
+        md_path = notes_root / f["folder"] / f["track"]
+        try:
+            meta, body = parse_file(md_path)
+            # Defensive re-check: `folder`/`track` on a finding lose any
+            # intermediate path segment (e.g. `known/archive/old.md` reports
+            # folder="known", track="old.md"), so a same-named file elsewhere
+            # under `folder` (archived vs. not) could otherwise collide here.
+            # Confirm the file we resolved still carries the OLD value this
+            # finding was raised against before writing — a mismatch means
+            # we resolved the wrong file, not that the finding is stale.
+            current = meta.get("github") if isinstance(meta, dict) else None
+            current_repo = current.get("repo") if isinstance(current, dict) else None
+            if current_repo != f["old"]:
+                entry["error"] = (
+                    f"resolved path {md_path} does not carry the expected old "
+                    f"value ({f['old']!r}, found {current_repo!r}) — refusing "
+                    "to write; likely a nested/archived track name collision"
+                )
+                ledger.append(entry)
+                continue
+            meta["github"]["repo"] = f["new"]
+            write_file(md_path, meta, body)
+            entry["fixed"] = True
+            changed_paths.append(rel)
+        except Exception as e:
+            entry["error"] = str(e)
+        ledger.append(entry)
+
+    if auto_commit_enabled and changed_paths:
+        ok_after, dirty_after = dirty_paths_checked(notes_root)
+        if ok_after:
+            delta = sorted(set(dirty_after) - dirty_before)
+            if delta:
+                auto_commit(notes_root, "doctor: fix stale repo identity in track frontmatter",
+                            paths=delta)
+    return ledger, False
+
+
+def _print_json(payload):
+    print(json.dumps(payload))
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, {"--json", "--fix"})
+    want_json = bool(flags.get("--json"))
+    want_fix = bool(flags.get("--fix"))
+
+    cfg, fatal = _load_config_safely()
+    if fatal is not None:
+        if want_json:
+            _print_json({"fatal": fatal, "attempts": [], "findings": []})
+            return 0
+        print(f"ERROR: work-plan config could not be loaded ({fatal}) — doctor cannot run.")
+        return 1
+
+    repos, shape_findings = _validate_repo_field_shapes(cfg)
+    findings = list(shape_findings) + _scan(cfg, repos)
+    attempts = []
+
+    if want_fix:
+        attempts += _apply_config_fixes(findings)
+        notes_root_raw = cfg.get("notes_root")
+        walkable, _ = _notes_root_status(cfg)
+        if walkable:
+            notes_root = Path(notes_root_raw).expanduser()
+            auto_enabled = notes_vcs_auto_commit(cfg)
+            fm_ledger, snapshot_failed = _apply_frontmatter_fixes(notes_root, findings, auto_enabled)
+            attempts += fm_ledger
+            if snapshot_failed:
+                print("WARN: notes-vcs status check failed — cannot safely determine "
+                      "which files are already dirty; no frontmatter fixes applied this run.",
+                      file=sys.stderr)
+
+        # Mandatory post-fix rescan, from disk.
+        cfg2, fatal2 = _load_config_safely()
+        if fatal2 is not None:
+            if want_json:
+                _print_json({"fatal": f"{fatal2} (residual state indeterminate after --fix)",
+                              "attempts": attempts, "findings": []})
+                return 0
+            print(f"ERROR: post-fix rescan failed ({fatal2}) — residual state indeterminate.")
+            return 1
+        repos2, shape_findings2 = _validate_repo_field_shapes(cfg2)
+        findings = list(shape_findings2) + _scan(cfg2, repos2)
+
+    if want_json:
+        _print_json({"attempts": attempts, "findings": findings})
+        return 0
+
+    for a in attempts:
+        thing = a["key"] or f"{a['folder']}/{a['track']}"
+        if a["fixed"]:
+            print(f"FIXED: {thing}: {a['old']} -> {a['new']}")
+        else:
+            print(f"ERROR fixing {thing}: {a['error']}")
+    if not findings:
+        if attempts:
+            print(f"{sum(1 for a in attempts if a['fixed'])} fixed, all clear.")
+        else:
+            print("No drift found.")
+        return 0
+    for f in findings:
+        prefix = "WARN (unfixed)" if attempts else "WARN"
+        print(f"{prefix}: {f['message']}")
+    print(f"{len(findings)} issue(s) found.")
+    return 1