@stylusnexus/work-plan 2026.6.10-1 → 2026.6.10-2

package/README.md

@@ -491,12 +491,13 @@ 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>` | Update issue STATE (open/closed, status labels) inside the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
+| `refresh-md <track>` `\|` `--all` `\|` `--repo=<key>` | Update issue STATE (open/closed, status labels) inside 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. |
 | `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. |
 | `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. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
 | `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
@@ -504,7 +505,7 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `coverage [--repo=<key>] [--list] [--limit=N]` | Report how many open issues are not in any track. `--list` prints titles. Read-only. |
 | `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft] [--yes]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). In an `--all`/`--repo` sweep it also detects **MOVEs** — an issue relabeled from one track to another in the same repo is moved (removed from the old track, added to the new); ambiguous targets stay as FLAGs. `--draft` previews ADDs/MOVEs/FLAGs without prompting or writing. `--yes` applies without prompting (non-interactive, e.g. the VS Code extension); PUBLIC-repo move destinations are skipped under `--yes`. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
-| `canonicalize <track>` | Add a canonical issue table to a track file (so `refresh-md` knows where to update). |
+| `canonicalize <track>` | Add a canonical issue table to a track file (so `refresh-md` knows where to update). The table carries a `Milestone` column and is ordered active-milestone-first — issues in the track's `milestone_alignment` milestone, then other milestones grouped (blank divider row between groups), then no-milestone last — so "what's next" sits above "someday" (#101). It's one table (not per-milestone sub-tables) so `refresh-md` re-derives it cleanly. |
 | `plan-status [--repo=<key>] [--json] [--stamp [--draft]] [--llm [--apply]] [--archive \| --issues] [--draft]` | Reach a verdict on every plan/spec doc in a repo by correlating its declared file-manifest against git + the filesystem: ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less / 🧳 foreign. Read-only by default. `--stamp` writes an idempotent status header into each doc (`--draft` previews); `--llm` runs a two-step AI verdict on prose/ambiguous docs; `--archive` moves dead plans to `archive/abandoned/` and `--issues` opens issues for partial plans (both gated, both honor `--draft`); `--json` for machine output. |
 
 Run `python3 ~/.claude/skills/work-plan/work_plan.py --help` for the full list with examples.

package/VERSION

@@ -1 +1 @@
-2026.06.10+9dce675
+2026.06.10+a3d10bf

package/package.json

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

@@ -8,9 +8,11 @@ Use --all to canonicalize every active track that doesn't yet have one.
 """
 from lib.config import load_config, ConfigError
 from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
-from lib.github_state import fetch_issues, state_to_status_label, format_assignees
+from lib.github_state import fetch_issues
 from lib.frontmatter import write_file
-from lib.status_table import CANONICAL_MARKER, find_canonical_status_tables, render_issue_row
+from lib.status_table import (
+    find_canonical_status_tables, render_canonical_table, insert_canonical_block,
+)
 from lib.prompts import parse_flags
 
 
@@ -75,10 +77,11 @@ def run(args: list[str]) -> int:
         issues = fetch_issues(track.repo, issue_nums)
         issues_by_num = {i["number"]: i for i in issues}
 
-        new_body = _insert_canonical_table(
-            track.body, issue_nums, issues_by_num, replace=force,
+        table_md = render_canonical_table(
+            issue_nums, issues_by_num,
             milestone_alignment=track.meta.get("milestone_alignment"),
         )
+        new_body = insert_canonical_block(track.body, table_md, replace=force)
         write_file(track.path, track.meta, new_body)
         print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
         any_changes = True
@@ -86,91 +89,3 @@ def run(args: list[str]) -> int:
     if not any_changes:
         print("Nothing to do.")
     return 0
-
-
-def _insert_canonical_table(body: str, issue_nums: list[int],
-                            issues_by_num: dict, replace: bool = False,
-                            milestone_alignment=None) -> str:
-    """Insert (or replace) a canonical table at the top of the body."""
-    table_md = _render_canonical_table(issue_nums, issues_by_num, milestone_alignment)
-
-    if replace:
-        # Strip existing canonical block (marker + heading + table + separator)
-        body = _strip_existing_canonical(body)
-
-    # Prepend table after any leading whitespace
-    body_stripped = body.lstrip("\n")
-    leading_whitespace = body[: len(body) - len(body_stripped)]
-    return leading_whitespace + table_md + "\n---\n\n" + body_stripped
-
-
-def _render_canonical_table(issue_nums: list[int], issues_by_num: dict,
-                            milestone_alignment=None) -> str:
-    lines = [
-        "## Issues (canonical)",
-        "",
-        f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
-        "",
-    ]
-
-    # Build a normalized issue list with compact milestone strings.
-    from lib.github_state import short_milestone
-    norm_issues = []
-    for num in sorted(issue_nums):
-        gh = issues_by_num.get(num, {})
-        ms = short_milestone(gh.get("milestone")) or None
-        norm_issues.append({"number": num, "milestone": ms, "_gh": gh})
-
-    from lib.export_model import group_issues_by_milestone
-    groups = group_issues_by_milestone(norm_issues, milestone_alignment)
-
-    if len(groups) <= 1:
-        # Single milestone group (or all null) — render flat, same as before.
-        lines.append("| # | Title | Assignee | Status |")
-        lines.append("|---|---|---|---|")
-        for num in sorted(issue_nums):
-            i = issues_by_num.get(num, {})
-            lines.append(render_issue_row(
-                num, i.get("title", "(not fetched)"),
-                format_assignees(i), state_to_status_label(i.get("state")),
-            ))
-        lines.append("")
-        return "\n".join(lines)
-
-    # Multiple milestone groups — render with section headings.
-    for label, issues in groups:
-        if label:
-            heading = f"{label} ({len(issues)})"
-        else:
-            heading = f"No milestone ({len(issues)})"
-        lines.append(f"### {heading}")
-        lines.append("")
-        lines.append("| # | Title | Assignee | Status |")
-        lines.append("|---|---|---|---|")
-        for norm in issues:
-            num = norm["number"]
-            i = norm["_gh"]
-            lines.append(render_issue_row(
-                num, i.get("title", "(not fetched)"),
-                format_assignees(i), state_to_status_label(i.get("state")),
-            ))
-        lines.append("")
-    return "\n".join(lines)
-
-
-def _strip_existing_canonical(body: str) -> str:
-    """Remove an existing canonical-table block from the top of the body."""
-    if CANONICAL_MARKER not in body:
-        return body
-    # Find the start of the heading "## Issues (canonical)" if present, else the marker
-    heading_idx = body.find("## Issues (canonical)")
-    marker_idx = body.find(CANONICAL_MARKER)
-    start = heading_idx if 0 <= heading_idx < marker_idx else marker_idx
-    # Find end: the next "---\n" separator after the marker
-    sep_idx = body.find("\n---\n", marker_idx)
-    if sep_idx == -1:
-        # No separator — strip just the marker line
-        end = body.find("\n", marker_idx) + 1
-    else:
-        end = sep_idx + len("\n---\n")
-    return body[:start] + body[end:].lstrip("\n")

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

@@ -3,7 +3,10 @@ from lib.config import load_config, ConfigError
 from lib.tracks import discover_tracks, find_track_by_name, filter_tracks_by_repo, parse_track_repo_arg, AmbiguousTrackError
 from lib.github_state import fetch_issues, state_to_status_label
 from lib.frontmatter import write_file
-from lib.status_table import find_all_status_tables, find_canonical_status_tables, sync_missing_rows, ISSUE_NUM_RE
+from lib.status_table import (
+    find_all_status_tables, find_canonical_status_tables, sync_missing_rows,
+    render_canonical_table, insert_canonical_block, ISSUE_NUM_RE,
+)
 from lib.prompts import prompt_yes_no, parse_flags
 
 
@@ -81,7 +84,7 @@ def _refresh_many(tracks: list, yes: bool) -> int:
 
         # Frontmatter is canonical for membership: issues listed there but
         # missing from the table need a fresh row (issue #77). Fetch the union
-        # so appended rows carry live title/assignee/status too.
+        # so rows carry live title/assignee/status too.
         frontmatter_nums = track.meta.get("github", {}).get("issues") or []
         fetch_nums = sorted(all_issue_nums | set(frontmatter_nums))
         if not fetch_nums:
@@ -91,55 +94,121 @@ 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}
 
-        lines = track.body.split("\n")
-        cell_updates = 0
-        for table in tables:
-            sidx = table["status_col_index"]
-            for row in table["rows"]:
-                nums = []
-                for cell in row["cells"]:
-                    nums.extend(int(m) for m in ISSUE_NUM_RE.findall(cell))
-                for num in nums:
-                    if num not in state_by_num:
-                        continue
-                    new_status = state_by_num[num]
-                    if sidx >= len(row["cells"]):
-                        continue
-                    current = row["cells"][sidx].strip()
-                    if current == new_status.strip():
-                        continue
-                    new_label = new_status.strip().split(" ", 1)[-1].lower()
-                    if new_label and new_label in current.lower():
-                        continue
-                    new_cells = list(row["cells"])
-                    new_cells[sidx] = " " + new_status + " "
-                    lines[row["line_idx"]] = "|" + "|".join(new_cells) + "|"
-                    cell_updates += 1
-
-        new_body = "\n".join(lines)
-        # Slot in rows for frontmatter issues missing from the table, each at
-        # its frontmatter-order position. Cell updates above preserve the line
-        # count, so the table's line indices stay valid for sync_missing_rows.
-        new_body, rows_added = sync_missing_rows(new_body, frontmatter_nums, issues_by_num)
+        if canonical:
+            # Canonical table → RE-DERIVE the whole block from frontmatter
+            # membership + live data, milestone-ordered (#101). Re-deriving from
+            # the one shared renderer is what keeps the markdown table from
+            # decaying: order, columns, missing rows, and statuses are all
+            # rebuilt every run, so it can't drift from the viewer.
+            new_body, detail = _rederive_canonical(
+                track, canonical, frontmatter_nums, issues_by_num, state_by_num
+            )
+        else:
+            new_body, detail = _refresh_narrative(
+                track, tables, frontmatter_nums, issues_by_num, state_by_num
+            )
 
         if new_body == track.body:
             continue
-        pending.append((track, new_body, cell_updates, rows_added))
+        pending.append((track, new_body, detail))
 
     if not pending:
         print("All tracks in sync.")
         return 0
 
     print(f"Pending updates across {len(pending)} track(s):\n")
-    for track, _, cells, added in pending:
-        added_str = f", {added} row(s) added" if added else ""
-        print(f"  {track.path.name:50}  {cells} cell(s){added_str}")
+    for track, _, detail in pending:
+        print(f"  {track.path.name:50}  {detail}")
 
     if not yes and not prompt_yes_no("\nApply all? [y/N]"):
         print("Cancelled.")
         return 0
 
-    for track, new_body, _, _ in pending:
+    for track, new_body, _ in pending:
         write_file(track.path, track.meta, new_body)
     print(f"\n✓ Updated {len(pending)} file(s).")
     return 0
+
+
+def _rederive_canonical(track, canonical_tables, frontmatter_nums,
+                        issues_by_num, state_by_num):
+    """Rebuild the canonical block, milestone-ordered, from live data.
+
+    Returns (new_body, detail_str). detail reports rows added vs. the old table
+    and status changes, falling back to a format/order note when the only
+    change is reordering or the one-time 4→5 column migration."""
+    old_nums, old_status = set(), {}
+    for table in canonical_tables:
+        sidx = table["status_col_index"]
+        for row in table["rows"]:
+            row_nums = [int(m) for cell in row["cells"]
+                        for m in ISSUE_NUM_RE.findall(cell)]
+            for num in row_nums:
+                old_nums.add(num)
+                if sidx < len(row["cells"]):
+                    old_status[num] = row["cells"][sidx].strip()
+
+    table_md = render_canonical_table(
+        frontmatter_nums, issues_by_num,
+        milestone_alignment=track.meta.get("milestone_alignment"),
+    )
+    new_body = insert_canonical_block(track.body, table_md, replace=True)
+
+    rows_added = len(set(frontmatter_nums) - old_nums)
+    # Frontmatter is membership truth: a row in the old table but no longer in
+    # frontmatter is dropped on re-derive. Surface it so an approving user can
+    # see a deletion, not just additions.
+    rows_removed = len(old_nums - set(frontmatter_nums))
+    status_changes = sum(
+        1 for n in frontmatter_nums
+        if n in old_status and n in state_by_num
+        and old_status[n] != state_by_num[n].strip()
+    )
+    bits = []
+    if status_changes:
+        bits.append(f"{status_changes} status change(s)")
+    if rows_added:
+        bits.append(f"{rows_added} row(s) added")
+    if rows_removed:
+        bits.append(f"{rows_removed} row(s) removed")
+    detail = ", ".join(bits) if bits else "canonical table re-derived"
+    return new_body, detail
+
+
+def _refresh_narrative(track, tables, frontmatter_nums, issues_by_num, state_by_num):
+    """Original behavior for tracks WITHOUT a canonical table: update status
+    cells in narrative tables in place, then slot in missing frontmatter rows.
+    Conservative — never reorders or restructures a hand-written table."""
+    lines = track.body.split("\n")
+    cell_updates = 0
+    for table in tables:
+        sidx = table["status_col_index"]
+        for row in table["rows"]:
+            nums = []
+            for cell in row["cells"]:
+                nums.extend(int(m) for m in ISSUE_NUM_RE.findall(cell))
+            for num in nums:
+                if num not in state_by_num:
+                    continue
+                new_status = state_by_num[num]
+                if sidx >= len(row["cells"]):
+                    continue
+                current = row["cells"][sidx].strip()
+                if current == new_status.strip():
+                    continue
+                new_label = new_status.strip().split(" ", 1)[-1].lower()
+                if new_label and new_label in current.lower():
+                    continue
+                new_cells = list(row["cells"])
+                new_cells[sidx] = " " + new_status + " "
+                lines[row["line_idx"]] = "|" + "|".join(new_cells) + "|"
+                cell_updates += 1
+
+    new_body = "\n".join(lines)
+    # Slot in rows for frontmatter issues missing from the table, each at its
+    # frontmatter-order position. Cell updates preserve the line count, so the
+    # table's line indices stay valid for sync_missing_rows.
+    new_body, rows_added = sync_missing_rows(new_body, frontmatter_nums, issues_by_num)
+
+    added_str = f", {rows_added} row(s) added" if rows_added else ""
+    return new_body, f"{cell_updates} cell(s){added_str}"

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

@@ -0,0 +1,243 @@
+"""rename-track subcommand — rename an existing active track's slug + file.
+
+Resolves <old-slug> to a single active Track, renames its .md file on disk,
+updates the frontmatter `track` field + `last_touched`, and (for shared tracks)
+optionally commits the move with --commit. Cross-references in sibling tracks'
+`depends_on` lists are warned about, or rewritten with --fix-refs.
+
+Non-goals: no bulk rename, no body search-and-replace, no archive rename
+(archived tracks aren't discovered, so they can't be targeted).
+
+Usage:
+  rename-track <old-slug | old@repo> <new-slug>
+               [--repo=<key>] [--fix-refs] [--commit] [--confirm=<token>]
+"""
+import json
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError, is_valid_git_repo
+from lib.tracks import (
+    discover_tracks,
+    find_track_by_name,
+    parse_track_repo_arg,
+    AmbiguousTrackError,
+)
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+# Same slug rule as new-track: lowercase letters/digits/hyphens, starts with letter.
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def _git_commit_rename(
+    old_path: Path, new_path: Path, old_slug: str, new_slug: str
+) -> None:
+    """Stage the old + new paths and commit a single shared-track rename.
+
+    Path-scoped (never `git add .`). git detects the move as a rename at commit
+    time from content similarity. Non-fatal: any git failure warns and returns.
+    """
+    # The clone root is .work-plan/'s parent.
+    clone_root = new_path.parent.parent
+    if not is_valid_git_repo(clone_root):
+        print("⚠ --commit ignored: track is private (not in a git repo)")
+        return
+
+    # Determine current branch name for the success message.
+    branch = "HEAD"
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(clone_root), "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True, text=True, check=False,
+        )
+        if result.returncode == 0:
+            branch = result.stdout.strip()
+    except OSError:
+        pass
+
+    # Stage ONLY the two affected paths (old deletion + new addition).
+    try:
+        subprocess.run(
+            ["git", "-C", str(clone_root), "add", str(old_path), str(new_path)],
+            capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as e:
+        msg = getattr(e, "stderr", str(e))
+        print(f"⚠ --commit: git add failed ({msg.strip()!r}) — continuing without commit")
+        return
+
+    commit_msg = f"chore: rename shared track '{old_slug}' → '{new_slug}'"
+    try:
+        subprocess.run(
+            ["git", "-C", str(clone_root), "commit", "-m", commit_msg],
+            capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as e:
+        msg = getattr(e, "stderr", str(e))
+        print(f"⚠ --commit: git commit failed ({msg.strip()!r}) — continuing without commit")
+        return
+
+    print(f"✓ committed rename '{old_slug}' → '{new_slug}' to {branch}")
+
+
+def _fix_cross_references(
+    tracks: list, renamed: object, old_slug: str, new_slug: str, *, apply: bool
+) -> int:
+    """Find sibling tracks in the same repo whose `depends_on` lists old_slug.
+
+    With apply=True, rewrite each occurrence to new_slug and persist the file;
+    otherwise just report. Returns the number of referring tracks found.
+    """
+    referrers = [
+        t for t in tracks
+        if t is not renamed
+        and t.has_frontmatter
+        and t.repo == renamed.repo
+        and old_slug in (t.meta.get("depends_on") or [])
+    ]
+    if not referrers:
+        return 0
+
+    if apply:
+        for t in referrers:
+            t.meta["depends_on"] = [
+                new_slug if dep == old_slug else dep
+                for dep in t.meta.get("depends_on") or []
+            ]
+            write_file(t.path, t.meta, t.body)
+        print(
+            f"✓ updated depends_on in {len(referrers)} track(s): "
+            + ", ".join(t.name for t in referrers)
+        )
+    else:
+        print(
+            f"⚠ {len(referrers)} track(s) still depend on '{old_slug}': "
+            + ", ".join(t.name for t in referrers)
+        )
+        print("  Re-run with --fix-refs to rewrite their depends_on to the new slug.")
+    return len(referrers)
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--repo", "--confirm", "--fix-refs", "--commit"}
+    )
+
+    if len(positional) < 2:
+        print(
+            "usage: work_plan.py rename-track <old-slug | old@repo> <new-slug>"
+            " [--repo=<key>] [--fix-refs] [--commit] [--confirm=<token>]"
+        )
+        return 2
+
+    old_arg = positional[0]
+    new_slug = positional[1]
+
+    name_from_arg, repo_from_arg = parse_track_repo_arg(old_arg)
+    old_name = name_from_arg
+    repo_qualifier = repo_from_arg or (
+        flags.get("--repo") if flags.get("--repo") is not True else None
+    )
+
+    # Validate the new slug up front (cheap, no I/O).
+    if not _SLUG_RE.fullmatch(new_slug):
+        print(
+            f"ERROR: '{new_slug}' is not a valid slug."
+            " Use lowercase letters, digits, hyphens; must start with a letter."
+        )
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    try:
+        track = find_track_by_name(old_name, tracks, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching '{old_name}'.")
+        return 1
+
+    if new_slug == track.name:
+        print(f"ERROR: '{new_slug}' is already the track's slug — nothing to rename.")
+        return 2
+
+    # Reject if a track with new_slug already exists in the same repo/tier
+    # (same target directory). new_path.exists() is the authoritative check.
+    new_path = track.path.parent / f"{new_slug}.md"
+    if new_path.exists():
+        print(f"ERROR: a track '{new_slug}' already exists at {new_path}")
+        return 2
+
+    # Public-repo confirm gate — fires BEFORE any write or move. Mirrors close.
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, track.repo, new_slug)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{track.repo} is PUBLIC (or visibility unknown); "
+                f"renaming '{track.name}' → '{new_slug}' will be written there."
+            ),
+            "token": make_token(track.repo, new_slug),
+        }))
+        return 0
+
+    # ------------------------------------------------------------------
+    # Perform the rename: write the rewritten frontmatter (track slug +
+    # last_touched) to the NEW path FIRST, then remove the old file. Doing
+    # it in this order means a write_file failure (yq error, symlink refusal)
+    # leaves the original intact — no half-renamed state where the filename
+    # and the frontmatter `track` field disagree.
+    # ------------------------------------------------------------------
+    old_path = track.path
+    old_slug = track.name
+
+    track.meta["track"] = new_slug
+    track.meta["last_touched"] = datetime.now().strftime("%Y-%m-%dT%H:%M")
+
+    write_file(new_path, track.meta, track.body)
+    old_path.unlink()
+    track.path = new_path
+    track.name = new_slug
+
+    is_shared = getattr(track, "tier", None) == "shared"
+    if is_shared:
+        print(f"✓ Renamed shared track '{old_slug}' → '{new_slug}' at {new_path}")
+    else:
+        notes_root = Path(cfg["notes_root"]).expanduser()
+        try:
+            display = new_path.relative_to(notes_root)
+        except ValueError:
+            display = new_path
+        print(f"✓ Renamed track '{old_slug}' → '{new_slug}' at {display}")
+
+    # ------------------------------------------------------------------
+    # --commit: stage + commit the rename to the shared repo (non-fatal).
+    # ------------------------------------------------------------------
+    if "--commit" in flags:
+        if is_shared:
+            _git_commit_rename(old_path, new_path, old_slug, new_slug)
+        else:
+            print("⚠ --commit ignored: track is private (not in a git repo)")
+    elif is_shared:
+        print("  ↑ shared track — commit + push to share this rename with teammates.")
+
+    # ------------------------------------------------------------------
+    # Cross-reference hygiene: sibling tracks that depend_on the old slug.
+    # ------------------------------------------------------------------
+    _fix_cross_references(
+        tracks, track, old_slug, new_slug, apply="--fix-refs" in flags
+    )
+
+    return 0