@stylusnexus/work-plan 2026.6.10 → 2026.6.11

package/README.md

@@ -109,7 +109,7 @@ flowchart TB
   - For tracks where you don't want to bother curating at all, set `next_up_auto: true` in the track's frontmatter — `brief` will then derive the list live each invocation, ignoring whatever's stored.
 - **Weekly** → `hygiene` runs `refresh-md --all` + `reconcile --all` + `duplicates` in sequence to keep status icons, GitHub labels, and dedup state honest.
 
-> **When should I run `refresh-md`?** Any time you close or merge issues and want the track body to reflect the new state. `handoff` rewrites the status table for one track on every run, but `brief` reads GitHub live without writing anything back — so a track you haven't `handoff`'d recently stays stale on disk. `refresh-md <track>` (or **Refresh Track Body** in VS Code) fixes that on-demand; `hygiene` sweeps all tracks weekly.
+> **When should I run `refresh-md`?** Any time you close or merge issues and want the track body to reflect the new state. `handoff` rewrites the status table for one track on every run, but `brief` reads GitHub live without writing anything back — so a track you haven't `handoff`'d recently stays stale on disk. `refresh-md <track>` (or **Sync Issue States from GitHub** in VS Code) fixes that on-demand; `hygiene` sweeps all tracks weekly.
 
 > **GitHub access is read-only.** The toolkit never writes to GitHub. All issue data comes from read-only `gh` CLI calls (`gh issue list`, `gh issue view`). Every write (frontmatter, status table, session log) goes to your local markdown files only.
 
@@ -148,8 +148,8 @@ The CLI never auto-pushes. When you create or update a shared track, it prints a
 **Multi-repo disambiguation:** if the same track slug exists in two repos, qualify with `@<repo>` or `--repo=<key>`:
 
 ```bash
-/work-plan slot 4234 auth-flow@critforge
-/work-plan close auth-flow --repo=critforge
+/work-plan slot 4234 auth-flow@myproject
+/work-plan close auth-flow --repo=myproject
 ```
 
 ## Plan & doc liveness (`plan-status`)
@@ -448,8 +448,12 @@ repos:
   myproject:
     github: your-org/myproject
     local: /path/to/local/checkout           # optional, enables in-progress detection
+notes_vcs:
+  auto_commit: true                          # opt-in local history for notes_root (set by `notes-vcs init`)
 ```
 
+`notes_vcs.auto_commit` is added by `/work-plan notes-vcs init` (or `enable`) — when on, every track-mutating command commits `notes_root` so private-tier edits are undoable. Absent → off.
+
 ### Where your config lives
 
 The active config the skill reads is **`~/.claude/work-plan/config.yml`** — created by `install.sh` (or `install.ps1`) on first run. There's no template file in the repo to confuse with the runtime config; install just writes the right two lines directly.
@@ -487,24 +491,26 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | Subcommand | What it does |
 |---|---|
 | `brief [--repo=<key>]` | Multi-track snapshot of all active tracks across configured repos. `--repo=<key>` filters to one project (matches the folder name under `notes_root` or the `org/repo` GitHub slug; archived-reopen callouts are also scoped). |
-| `handoff <track> [--auto-next \| --set-next 1,2,3]` | Wrap up a work block. Writes a `### Session — <ts>` entry. `--auto-next` suggests a priority-sorted top-3 from open issues (interactive: apply / edit / skip). `--set-next 1,2,3` is the explicit form. Without either flag, just captures the session summary and reads any pre-existing `next_up`. |
+| `handoff <track> [--auto-next \| --set-next 1,2,3]` | Wrap up a work block. Writes a `### Session — <ts>` entry. `--auto-next` suggests a priority-sorted top-3 from open issues (interactive: apply / edit / skip). `--set-next 1,2,3` is the explicit form — note it writes the session entry too; for a field-only `next_up` change with no session log, use `set next_up=…`. Without either flag, just captures the session summary and reads any pre-existing `next_up`. |
 | `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>` | Sync issue STATE (open/closed, status labels) from GitHub into the track body's status table. Does NOT change track membership — this is the right tool for "refresh the work I just completed." For a **canonical** table it re-derives the whole block from live data, milestone-ordered (active milestone first; see `canonicalize`), so the table self-heals and stays grouped instead of decaying; narrative (non-canonical) tables are updated conservatively in place. `--all` sweeps every active track; `--repo=<key>` scopes the sweep to one repo. |
 | `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. |
+| `notes-vcs <init\|enable\|disable\|status\|undo> [<sha>] [--no-enable] [--json]` | Opt-in **local** version control for the private `notes_root` tier — history/undo for tracks on your machine, never pushed. `init` git-inits `notes_root` as a personal repo (baseline commit of existing tracks) and turns on auto-commit (`--no-enable` skips that). For safety it **refuses** a `notes_root` that already has a git remote or is a repo work-plan didn't create. When on, every track-mutating command (`slot`/`group`/`handoff`/`close`/`set`/…) commits **only the files it changed** (pre-existing uncommitted edits are left alone) as an undoable commit. The shared tier is unaffected — it's versioned by its own repo. `status` shows whether `notes_root` is a repo, whether auto-commit is on, and the last commit (`--json` for the machine shape the VS Code viewer polls). `undo [<sha>]` reverts a commit (default HEAD) — reverses the last edit. |
 | `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). |
 | `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
 | `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`. |
+| `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 the label drift (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+a6052bf
+2026.06.11+8c21445

package/package.json

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

@@ -15,10 +15,10 @@ Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file th
 | `/work-plan brief` | Starting work or after a gap. Multi-track snapshot. |
 | `/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 "Refresh Track Body" 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 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 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 refresh-md <track> \| --all \| --repo=<key>` | **Pull live GitHub state into a track's status table.** Run this after closing or merging issues — it re-fetches each issue's open/closed state from GitHub and rewrites the status cells in the track body, which refreshes the dependency graph and `next_up` display. `--all` sweeps every active track; `--repo=<key>` scopes to one repo. In VS Code: right-click a track → **Refresh Track Body**. |
+| `/work-plan refresh-md <track> \| --all \| --repo=<key>` | **Pull live GitHub state into a track's status table.** Run this after closing or merging issues — it re-fetches each issue's open/closed state from GitHub and rewrites the status cells in the track body, which refreshes the dependency graph and `next_up` display. `--all` sweeps every active track; `--repo=<key>` scopes to one repo. In VS Code: right-click a track → **Sync Issue States from GitHub**. |
 | `/work-plan list [--all]` | List active tracks (or all including parked/archived). |
 | `/work-plan init <path>` | Add frontmatter to a new track .md file. |
 | `/work-plan 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. |
@@ -88,6 +88,8 @@ Track files live in one of two places:
 
 **Routing logic (automatic):** if a repo has a registered `local:` path that is a valid git repo, new tracks go into `.work-plan/` by default. Pass `--private` to any write command to route to `notes_root` instead.
 
+**Local history for the private tier (opt-in):** the shared tier already gets version control from its repo. For the private tier, `/work-plan notes-vcs init` git-inits `notes_root` as a *personal, never-pushed* repo and turns on auto-commit — every track-mutating command then writes an undoable commit to `notes_root`. `notes-vcs status` reports the state; `enable`/`disable` toggle it. Off until you run it.
+
 **Setup shared tracks for a repo:**
 ```
 /work-plan init-repo myproject --github=org/myproject --local=/path/to/clone
@@ -97,8 +99,8 @@ Track files live in one of two places:
 
 **Disambiguation when the same track slug exists in two repos:**
 ```
-/work-plan slot 4234 auth-flow@critforge   # @repo qualifier
-/work-plan close auth-flow --repo=critforge  # --repo=<key> flag
+/work-plan slot 4234 auth-flow@myproject   # @repo qualifier
+/work-plan close auth-flow --repo=myproject  # --repo=<key> flag
 ```
 
 Both forms work on: `slot`, `close`, `handoff`, `canonicalize`, `refresh-md`, `reconcile`, `set`.

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/handoff.py

@@ -19,6 +19,7 @@ from lib.session_log import append_session_log, SESSION_LOG_HEADER
 from lib.git_state import (
     has_uncommitted, current_branch, parse_iso_timestamp,
     gap_seconds_to_label, uncommitted_file_count, commits_ahead,
+    is_safe_ref, GIT_TIMEOUT,
 )
 from lib.github_state import fetch_issues, state_to_status_label, extract_priority, short_milestone
 from lib.status_table import update_row_status, sync_missing_rows, find_canonical_status_tables, ISSUE_NUM_RE
@@ -514,12 +515,20 @@ def _recent_commits(track, since_dt) -> list[dict]:
 
     if branches:
         for b in branches:
-            proc = subprocess.run(
-                ["git", "-C", str(track.local_path), "log", b,
-                 f"--since={since_iso}",
-                 "--pretty=format:%H|%s|%cI"],
-                capture_output=True, text=True,
-            )
+            # A branch name from frontmatter is passed as a positional rev; a
+            # dash-led value (e.g. `--output=/path`) would be read by git as an
+            # option → arbitrary-file write. Reject before use (#192).
+            if not is_safe_ref(str(b)):
+                continue
+            try:
+                proc = subprocess.run(
+                    ["git", "-C", str(track.local_path), "log", b,
+                     f"--since={since_iso}",
+                     "--pretty=format:%H|%s|%cI"],
+                    capture_output=True, text=True, timeout=GIT_TIMEOUT,
+                )
+            except (subprocess.TimeoutExpired, OSError):
+                continue
             if proc.returncode != 0 or not proc.stdout.strip():
                 continue
             for line in proc.stdout.strip().split("\n"):

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

@@ -67,12 +67,22 @@ def run(args: list[str]) -> int:
             return 1
         folder = None
     else:
-        notes_root = Path(cfg["notes_root"])
+        # Containment guard (#195): a non-shared target MUST live under
+        # notes_root. Without this, `init /etc/anything` (any user-writable
+        # file with no frontmatter) would get frontmatter prepended via
+        # write_file, clobbering it. `path` is already resolved; resolve
+        # notes_root too so the comparison is symlink/relative-safe.
+        notes_root = Path(cfg["notes_root"]).expanduser().resolve()
         try:
             rel = path.relative_to(notes_root)
-            folder = rel.parts[0] if len(rel.parts) > 1 else None
         except ValueError:
-            folder = None
+            print(
+                f"ERROR: {path} is not inside notes_root ({notes_root}) or a"
+                " registered .work-plan/ directory — refusing to write"
+                " frontmatter outside the tracked tree."
+            )
+            return 1
+        folder = rel.parts[0] if len(rel.parts) > 1 else None
         repo = resolve_github_for_folder(folder, cfg) if folder else None
 
     issue_nums = sorted(set(int(m) for m in re.findall(r"#(\d+)", body)))

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

@@ -3,6 +3,7 @@
 Non-interactive: --github is required; --local is optional (no prompts).
 """
 import json
+import os
 import re
 import subprocess
 from pathlib import Path
@@ -113,11 +114,16 @@ def run(args: list[str]) -> int:
     if local:
         repo_block["local"] = local
 
-    yq_expr = f'.repos.{key} = {json.dumps(repo_block)}'
+    # `key` is validated against ^[a-z][a-z0-9-]*$ above, so it's safe in the yq
+    # path. The repo block is passed as an OPAQUE env value via env() (parsed as
+    # YAML/JSON) rather than interpolated into the expression — uniform with the
+    # strenv() hardening in set-notes-root (#196).
+    env = {**os.environ, "WP_REPO_BLOCK": json.dumps(repo_block)}
+    yq_expr = f".repos.{key} = env(WP_REPO_BLOCK)"
     try:
         subprocess.run(
             ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
-            check=True, capture_output=True, text=True,
+            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/new_track.py

@@ -103,6 +103,13 @@ def run(args: list[str]) -> int:
     elif "/" in repo_arg:
         github = repo_arg
         folder = repo_arg.rsplit("/", 1)[-1]
+        # Validate the derived folder segment (#195). `rsplit` caps traversal at
+        # one segment, but a slug like `x/..` yields folder=".." → the track
+        # would be written one level ABOVE notes_root. A real GitHub repo name
+        # matches [A-Za-z0-9._-]+ and is never "." / ".." — reject anything else.
+        if folder in ("", ".", "..") or not re.fullmatch(r"[A-Za-z0-9._-]+", folder):
+            print(f"ERROR: cannot derive a safe notes folder from '{repo_arg}'.")
+            return 2
     else:
         print(
             f"ERROR: unknown repo '{repo_arg}' — pass a configured key"

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

@@ -0,0 +1,172 @@
+"""notes-vcs subcommand — opt-in local version control for notes_root (#103).
+
+Actions:
+  init     git-init notes_root as a personal, never-pushed repo (initial commit
+           of existing tracks), then enable auto-commit unless --no-enable.
+  enable   turn on auto-commit after track-mutating commands.
+  disable  turn it off (history is kept; just stop adding new commits).
+  status   report whether notes_root is under git, whether auto-commit is on,
+           and the last commit — plus a nudge to `init` when it isn't a repo.
+           Add --json for the machine-readable shape the VS Code viewer polls.
+  undo     revert a commit in notes_root (default HEAD). The git side of the
+           viewer's Undo button (#224); on the CLI it reverses the last edit.
+
+Config writes use the same opaque-env `yq strenv` pattern as set-notes-root
+(#191): the value is never interpolated into the yq expression.
+
+Usage: notes-vcs <init|enable|disable|status|undo> [<sha>] [--no-enable] [--json]
+"""
+import json as _json
+import os
+import subprocess
+from pathlib import Path
+
+from lib.config import (
+    load_config, ConfigError, DEFAULT_CONFIG_PATH, notes_vcs_auto_commit,
+)
+from lib.prompts import parse_flags
+from lib import notes_vcs
+
+_ACTIONS = ("init", "enable", "disable", "status", "undo")
+
+
+def _set_auto_commit(value: bool) -> bool:
+    """Persist notes_vcs.auto_commit=<value> into config.yml via yq. The bool
+    travels as an opaque env value (strenv), never interpolated into the
+    expression. Returns True on success."""
+    env = {**os.environ, "WP_VCS": "true" if value else "false"}
+    try:
+        subprocess.run(
+            ["yq", "-i", ".notes_vcs.auto_commit = (strenv(WP_VCS) == \"true\")",
+             str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True, env=env,
+        )
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return False
+
+
+def _status_dict(notes_root: Path, cfg: dict) -> dict:
+    """Machine-readable state for the VS Code viewer (#224). last_commit_sha is
+    the handle the viewer diffs across a write to decide whether to offer Undo."""
+    is_root = notes_vcs.is_git_root(notes_root)
+    return {
+        "notes_root": str(notes_root),
+        "under_git": notes_vcs.is_under_git(notes_root),
+        "is_root": is_root,
+        "auto_commit": notes_vcs_auto_commit(cfg),
+        "last_commit_sha": notes_vcs.last_commit_sha(notes_root) if is_root else None,
+        "head_parent_sha": notes_vcs.head_parent_sha(notes_root) if is_root else None,
+        "last_commit_subject": notes_vcs.last_commit_summary(notes_root) if is_root else None,
+        "dirty": notes_vcs.has_changes(notes_root) if is_root else False,
+    }
+
+
+def _print_status(notes_root: Path, cfg: dict) -> None:
+    on = notes_vcs_auto_commit(cfg)
+    print(f"notes_root: {notes_root}")
+    if notes_vcs.is_git_root(notes_root):
+        print("git:         ✓ local repo (notes_root is the git root)")
+        last = notes_vcs.last_commit_summary(notes_root)
+        print(f"last commit: {last}" if last else "last commit: (none yet)")
+        if notes_vcs.has_changes(notes_root):
+            print("working tree: uncommitted changes present")
+    elif notes_vcs.is_under_git(notes_root):
+        print("git:         ⚠ inside another git repo (NOT its root) — "
+              "auto-commit is disabled here; move notes_root to its own folder.")
+    else:
+        print("git:         ✗ not a repo — run `work-plan notes-vcs init` to add local history")
+    print(f"auto-commit: {'on' if on else 'off'}")
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--no-enable", "--json"})
+
+    action = positional[0] if positional else "status"
+    if action not in _ACTIONS:
+        print(f"usage: work_plan.py notes-vcs <{'|'.join(_ACTIONS)}> "
+              "[<sha>] [--no-enable] [--json]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+    notes_root = Path(cfg["notes_root"]).expanduser()
+
+    if action == "status":
+        if "--json" in flags:
+            print(_json.dumps(_status_dict(notes_root, cfg)))
+        else:
+            _print_status(notes_root, cfg)
+        return 0
+
+    if action == "undo":
+        if not notes_vcs.is_git_root(notes_root):
+            print(f"ERROR: {notes_root} is not a git repo — nothing to undo.")
+            return 1
+        # Same boundary as init/auto-commit: never rewrite a repo we don't own
+        # or one with a remote (it could be an unrelated project clone).
+        if notes_vcs.has_remotes(notes_root) or not notes_vcs.is_owned(notes_root):
+            print(f"ERROR: {notes_root} is not a work-plan local-history repo "
+                  "(it has a git remote, or wasn't created by work-plan). "
+                  "Refusing to revert — undo only operates on personal history.")
+            return 1
+        sha = positional[1] if len(positional) > 1 else None
+        new_sha = notes_vcs.revert(notes_root, sha)
+        if not new_sha:
+            print(f"ERROR: failed to revert {sha or 'HEAD'} in {notes_root} "
+                  "(nothing to revert, or a conflict — resolve it manually).")
+            return 1
+        print(f"✓ Reverted {sha or 'HEAD'} — new commit {new_sha}.")
+        return 0
+
+    if action == "init":
+        if notes_vcs.is_under_git(notes_root) and not notes_vcs.is_git_root(notes_root):
+            print(f"ERROR: {notes_root} is inside another git repo but is not its "
+                  "root. Auto-commit would stage unrelated files there. Move "
+                  "notes_root to its own folder first (see set-notes-root).")
+            return 1
+        if notes_vcs.is_git_root(notes_root):
+            # Don't adopt an existing repo we didn't create, or one with a
+            # remote — private notes must never be pushable.
+            if notes_vcs.has_remotes(notes_root):
+                print(f"ERROR: {notes_root} already has a git remote. Local "
+                      "history must stay personal and never-pushed — point "
+                      "notes_root at a folder with no remote, or remove the "
+                      "remote first.")
+                return 1
+            if not notes_vcs.is_owned(notes_root):
+                print(f"ERROR: {notes_root} is an existing git repo not created "
+                      "by work-plan. Refusing to adopt it (it may hold unrelated "
+                      "history). Point notes_root at a fresh folder for local "
+                      "history.")
+                return 1
+        if not notes_vcs.init_repo(notes_root):
+            print(f"ERROR: failed to git-init {notes_root}. Is git installed?")
+            return 1
+        print(f"✓ Initialized local history at {notes_root} (personal repo — no remote).")
+        if "--no-enable" in flags:
+            print("  auto-commit left off — run `notes-vcs enable` to turn it on.")
+            return 0
+        if not _set_auto_commit(True):
+            return 1
+        print("✓ auto-commit enabled — track edits now create undoable commits.")
+        return 0
+
+    if action == "enable":
+        if not notes_vcs.is_git_root(notes_root):
+            print(f"WARN: {notes_root} is not a git repo yet. Run "
+                  "`work-plan notes-vcs init` first, or commits will be skipped.")
+        if not _set_auto_commit(True):
+            return 1
+        print("✓ auto-commit enabled.")
+        return 0
+
+    # action == "disable"
+    if not _set_auto_commit(False):
+        return 1
+    print("✓ auto-commit disabled (existing history kept).")
+    return 0