@stylusnexus/work-plan 2026.6.10 → 2026.6.11

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

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

@@ -5,6 +5,7 @@ folder. Config writes stay in the CLI (the engine), not the extension.
 
 Usage: set-notes-root <path>
 """
+import os
 import subprocess
 from pathlib import Path
 
@@ -38,12 +39,15 @@ def run(args: list[str]) -> int:
     # Ensure the target directory exists
     new_root.mkdir(parents=True, exist_ok=True)
 
-    # Write the new notes_root into config via yq (mikefarah/yq)
-    yq_expr = f'.notes_root = "{new_root}"'
+    # Write the new notes_root into config via yq (mikefarah/yq). The path is
+    # passed as an OPAQUE env value via strenv() — never interpolated into the
+    # yq expression — so a path containing `"` or yq operators cannot break out
+    # of the string literal and rewrite arbitrary config keys (#191).
+    env = {**os.environ, "WP_NEW_ROOT": str(new_root)}
     try:
         subprocess.run(
-            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
-            check=True, capture_output=True, text=True,
+            ["yq", "-i", ".notes_root = strenv(WP_NEW_ROOT)", str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True, env=env,
         )
     except subprocess.CalledProcessError as e:
         print(f"ERROR: yq failed to update config: {e.stderr}")

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

@@ -113,8 +113,18 @@ def _apply(cfg: dict) -> int:
 
     print(f"Applying {len(answers)} priority labels to {repo}...")
     for ans in answers:
-        num = ans["number"]
-        priority = ans["priority"]
+        # The answers file is model-written; coerce the issue number to int and
+        # skip malformed entries so a non-numeric value can't reach `gh` argv
+        # (and a malformed file can't crash the apply). (#196)
+        if not isinstance(ans, dict):
+            print(f"  SKIP: answer is not an object: {ans!r}")
+            continue
+        try:
+            num = int(ans["number"])
+        except (KeyError, TypeError, ValueError):
+            print(f"  SKIP: answer missing a numeric 'number': {ans!r}")
+            continue
+        priority = ans.get("priority")
         if priority not in ("P0", "P1", "P2", "P3"):
             print(f"  SKIP #{num}: invalid priority '{priority}'")
             continue

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

@@ -76,6 +76,17 @@ def is_valid_git_repo(path: Path) -> bool:
     return p.is_dir() and (p / ".git").exists()
 
 
+def notes_vcs_auto_commit(cfg: dict) -> bool:
+    """True when opt-in local VCS auto-commit is enabled for notes_root (#103).
+
+    Reads `notes_vcs.auto_commit` from config. Absent/malformed → False
+    (opt-in: the feature does nothing until the user turns it on, e.g. via
+    `work-plan notes-vcs init` or `notes-vcs enable`).
+    """
+    block = cfg.get("notes_vcs")
+    return bool(block.get("auto_commit")) if isinstance(block, dict) else False
+
+
 def resolve_github_for_folder(folder_name: str, cfg: dict) -> Optional[str]:
     entry = cfg.get("repos", {}).get(folder_name)
     return entry.get("github") if entry else None

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

@@ -21,12 +21,21 @@ def parse_file(path: Path) -> Tuple[dict, str]:
 
 
 def write_file(path: Path, meta: dict, body: str) -> None:
-    """Write markdown with frontmatter. Empty meta = body only."""
+    """Write markdown with frontmatter. Empty meta = body only.
+
+    Refuses to write through a symlink (#195): a track file that is a symlink to
+    a target outside the notes tree would otherwise let a write land on an
+    arbitrary file. Track files are never legitimately symlinks, so this rejects
+    nothing valid; raises ValueError if one is encountered.
+    """
+    p = Path(path)
+    if p.is_symlink():
+        raise ValueError(f"refusing to write through symlink: {p}")
     if not meta:
-        Path(path).write_text(body, encoding="utf-8")
+        p.write_text(body, encoding="utf-8")
         return
     yaml_text = _dict_to_yaml(meta)
-    Path(path).write_text(f"---\n{yaml_text}---\n{body}", encoding="utf-8")
+    p.write_text(f"---\n{yaml_text}---\n{body}", encoding="utf-8")
 
 
 def _yaml_to_dict(yaml_text: str) -> dict: