@stylusnexus/work-plan 2026.6.10-2 → 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.
 
@@ -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,11 +491,11 @@ 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." 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. |
+| `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. |
@@ -499,11 +503,12 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `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). 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. |

package/VERSION

@@ -1 +1 @@
-2026.06.10+a3d10bf
+2026.06.11+8c21445

package/package.json

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

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

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

@@ -0,0 +1,276 @@
+"""Opt-in local version control for the private notes_root tier (#103).
+
+The shared tier (`<repo>/.work-plan/`) is version-controlled by the repo it
+lives in. The private tier (`notes_root`, e.g. `Project Notes/`) is not — so a
+track edit (slot/group/handoff/close/set) has no history or undo. This module
+adds an opt-in, *personal, never-pushed* git repo at notes_root: every
+track-mutating command becomes an undoable commit + diff.
+
+Every helper here NEVER raises — git absence, a stuck lock, a slow filesystem,
+or a non-repo all resolve to "do nothing". A VCS failure must never change a
+command's exit code (the dispatcher relies on this).
+
+Safety rule: we only ever operate when notes_root is the git TOPLEVEL. If
+notes_root sits inside someone else's repo (the workspace, a clone), we refuse
+to `git add -A` there — that would sweep unrelated files into a foreign repo.
+`notes-vcs init` makes notes_root its own root, satisfying this.
+"""
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+# Bound every git subprocess so a stuck lock or slow FS can't stall the CLI
+# (mirrors git_state.GIT_TIMEOUT; kept local to avoid a cross-module coupling).
+GIT_TIMEOUT = 20
+
+_GITIGNORE = ".DS_Store\nThumbs.db\n"
+_INIT_COMMIT_MSG = "work-plan: initialize notes_root local history"
+
+# Local git-config marker stamped on the repos work-plan creates for local
+# history. We only ever auto-commit a repo carrying this marker, so we never
+# adopt (and commit into) an arbitrary pre-existing repo the user pointed
+# notes_root at.
+_OWNED_KEY = "workplan.localhistory"
+
+
+def _git(notes_root, *args, timeout: int = GIT_TIMEOUT):
+    """Run `git -C <notes_root> <args>`; return CompletedProcess or None.
+
+    None means git is missing, timed out, or the spawn failed — callers treat
+    it as "no data / could not act", preserving the never-raise contract.
+    """
+    try:
+        return subprocess.run(
+            ["git", "-C", str(notes_root), *args],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def is_git_root(notes_root: Path) -> bool:
+    """True only if notes_root is itself the toplevel of a git work tree.
+
+    A bare `.git` existence check would also pass for a subdirectory of a larger
+    repo, where `git add -A` would stage unrelated files. We compare the
+    resolved toplevel to the resolved notes_root so auto-commit only ever fires
+    on a repo we own.
+    """
+    if not notes_root:
+        return False
+    root = Path(notes_root).expanduser()
+    if not root.is_dir():
+        return False
+    proc = _git(root, "rev-parse", "--show-toplevel")
+    if proc is None or proc.returncode != 0:
+        return False
+    top = proc.stdout.strip()
+    if not top:
+        return False
+    try:
+        return Path(top).resolve() == root.resolve()
+    except OSError:
+        return False
+
+
+def is_under_git(notes_root: Path) -> bool:
+    """True if notes_root is inside ANY git work tree (root or subdir).
+
+    Used by status/nudge messaging to distinguish "not a repo at all" from
+    "inside a repo but not its root" (the latter we deliberately won't touch).
+    """
+    if not notes_root:
+        return False
+    root = Path(notes_root).expanduser()
+    if not root.is_dir():
+        return False
+    proc = _git(root, "rev-parse", "--is-inside-work-tree")
+    return proc is not None and proc.returncode == 0 and proc.stdout.strip() == "true"
+
+
+def has_changes(notes_root: Path) -> bool:
+    """True if the notes_root work tree has staged or unstaged changes."""
+    proc = _git(notes_root, "status", "--short")
+    return proc is not None and proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def has_remotes(notes_root: Path) -> bool:
+    """True if the repo has ANY configured remote.
+
+    A personal local-history repo must have none — otherwise private notes
+    could be pushed off the machine. Used to refuse enabling/committing history
+    on a remote-backed repo.
+    """
+    proc = _git(notes_root, "remote")
+    return proc is not None and proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def is_owned(notes_root: Path) -> bool:
+    """True only if work-plan created this repo for local history.
+
+    `init_repo` stamps a local git-config marker; auto-commit requires it, so we
+    never commit into a repo we don't control (e.g. an existing clone the user
+    pointed notes_root at).
+    """
+    proc = _git(notes_root, "config", "--local", "--get", _OWNED_KEY)
+    return proc is not None and proc.returncode == 0 and proc.stdout.strip() == "true"
+
+
+def mark_owned(notes_root: Path) -> bool:
+    """Stamp the ownership marker into the repo's local config. Returns success."""
+    proc = _git(notes_root, "config", "--local", _OWNED_KEY, "true")
+    return proc is not None and proc.returncode == 0
+
+
+def head_parent_sha(notes_root: Path) -> Optional[str]:
+    """Short sha of HEAD's first parent, or None (root commit / no commits / not
+    a repo). The viewer compares this to the previously-seen HEAD to confirm a
+    post-write commit sits directly on top before offering Undo (#224 safety)."""
+    proc = _git(notes_root, "rev-parse", "--short", "--verify", "HEAD^")
+    if proc is None or proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    return proc.stdout.strip()
+
+
+def dirty_paths(notes_root: Path) -> set:
+    """Set of work-tree paths with staged/unstaged changes (raw, quotepath off).
+
+    Empty set on any failure. Renames collapse to the destination path. Used by
+    the dispatcher to commit ONLY what a command changed, leaving pre-existing
+    dirty files untouched.
+    """
+    proc = _git(notes_root, "-c", "core.quotepath=false", "status", "--porcelain")
+    if proc is None or proc.returncode != 0:
+        return set()
+    paths = set()
+    for line in proc.stdout.splitlines():
+        if len(line) < 4:
+            continue
+        path = line[3:]
+        if " -> " in path:  # rename / copy → the destination path
+            path = path.split(" -> ", 1)[1]
+        if path:
+            paths.add(path)
+    return paths
+
+
+def last_commit_summary(notes_root: Path) -> Optional[str]:
+    """'<short-sha> <subject>' of HEAD, or None (no commits / not a repo)."""
+    proc = _git(notes_root, "log", "-1", "--pretty=format:%h %s")
+    if proc is None or proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    return proc.stdout.strip()
+
+
+def last_commit_sha(notes_root: Path) -> Optional[str]:
+    """Short sha of HEAD, or None (no commits / not a repo). The undo handle the
+    VS Code viewer diffs across a write to decide whether to offer Undo (#224)."""
+    proc = _git(notes_root, "log", "-1", "--pretty=format:%h")
+    if proc is None or proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    return proc.stdout.strip()
+
+
+def revert(notes_root: Path, sha: Optional[str] = None) -> Optional[str]:
+    """Revert `sha` (default HEAD) in notes_root; return the new commit's sha.
+
+    Keeps git inside the engine so callers (the CLI `undo` verb, the viewer's
+    Undo button) never shell out to git themselves. No-op (None) when notes_root
+    isn't a git root we OWN with no remote (same boundary as auto_commit — we
+    must never rewrite an unrelated project clone's history), when there's no
+    commit to revert, or when `sha` is unsafe (empty / dash-led — git would read
+    a dash-led value as an option). Never raises. Uses --no-edit (non-interactive).
+    """
+    root = Path(notes_root).expanduser()
+    if not is_git_root(root) or not is_owned(root) or has_remotes(root):
+        return None
+    target = sha if sha is not None else "HEAD"
+    # A dash-led ref would be parsed by git as an option, not a revision.
+    if not target or target.startswith("-"):
+        return None
+    proc = _git(root, "revert", "--no-edit", target)
+    if proc is None or proc.returncode != 0:
+        return None
+    return last_commit_sha(root)
+
+
+def init_repo(notes_root: Path) -> bool:
+    """git-init notes_root as a personal repo and make an initial commit.
+
+    Writes a small `.gitignore` (OS cruft only), stages everything, and commits
+    existing tracks so there's a baseline to diff against. Deliberately adds NO
+    remote — the private tier is never pushed. Returns True on a clean init +
+    initial commit, False on any failure (never raises).
+
+    Idempotent-ish: re-running on a repo WE own re-commits only if there's
+    something new. Refuses (returns False) to adopt a repo we did not create or
+    one that has a remote — private notes must never be pushable, and we won't
+    sweep an unrelated existing repo's files into history.
+    """
+    root = Path(notes_root).expanduser()
+    if not root.is_dir():
+        return False
+    if is_git_root(root):
+        # An existing repo: only proceed if it's one we own AND has no remote.
+        if has_remotes(root) or not is_owned(root):
+            return False
+    else:
+        if _git(root, "init") is None:
+            return False
+        # Stamp ownership immediately, before any commit, so this repo can never
+        # later be mistaken for a foreign one (and a remote added after init is
+        # still caught by auto_commit's per-commit no-remote check).
+        if not mark_owned(root):
+            return False
+    gitignore = root / ".gitignore"
+    if not gitignore.exists():
+        try:
+            gitignore.write_text(_GITIGNORE, encoding="utf-8")
+        except OSError:
+            return False
+    if _git(root, "add", "-A") is None:
+        return False
+    # Nothing to commit (e.g. re-init of an unchanged repo) is success, not error.
+    if not has_changes(root) and last_commit_summary(root) is not None:
+        return True
+    proc = _git(root, "commit", "-m", _INIT_COMMIT_MSG)
+    return proc is not None and proc.returncode == 0
+
+
+def auto_commit(notes_root: Path, message: str,
+                paths: Optional[list] = None) -> Optional[str]:
+    """Commit notes_root changes with `message`; return the new short SHA.
+
+    Safety gates (all must hold, else no-op None):
+      - notes_root is the git toplevel,
+      - it carries the ownership marker (work-plan created it), and
+      - it has NO remote (a personal, never-pushed history).
+
+    When `paths` is given, stages ONLY those paths so unrelated pre-existing
+    dirty files stay out of the commit; otherwise stages everything. Commits
+    only if something is actually staged. Never raises — a git failure here must
+    not change the calling command's exit code.
+    """
+    root = Path(notes_root).expanduser()
+    if not is_git_root(root) or not is_owned(root) or has_remotes(root):
+        return None
+    if paths is None:
+        if _git(root, "add", "-A") is None:
+            return None
+    else:
+        if not paths:
+            return None
+        if _git(root, "add", "--", *paths) is None:
+            return None
+    # Commit only what's staged — scoped `add` above keeps unrelated dirty files
+    # unstaged, so they're preserved rather than folded into this commit.
+    staged = _git(root, "diff", "--cached", "--quiet")
+    if staged is None or staged.returncode == 0:
+        return None
+    proc = _git(root, "commit", "-m", message)
+    if proc is None or proc.returncode != 0:
+        return None
+    head = _git(root, "rev-parse", "--short", "HEAD")
+    if head is None or head.returncode != 0:
+        return None
+    return head.stdout.strip() or None