@stylusnexus/work-plan 2026.6.10 → 2026.6.11-2

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

@@ -0,0 +1,314 @@
+"""plan-branch subcommand — bootstrap + share a repo's canonical plan branch (#260).
+
+The shared (`.work-plan/`) tier is pinned to ONE per-repo `plan_branch`, read and
+written through a dedicated git worktree (Phases 1+2). This command sets that up
+and shares it:
+
+  init <repo>   Create the plan branch + `.work-plan/` skeleton for <repo>, or
+                connect to a teammate's already-published one, and record
+                `plan_branch` in config. LOCAL ONLY — no network push. Default
+                branch is an ORPHAN `work-plan/plan` (zero shared history with
+                code, like gh-pages); override with --branch=<name>.
+  status <repo> Report the configured plan_branch: does it exist, is it
+                published to origin, how many local commits are unpushed.
+                Add --json for the machine shape.
+  push <repo>   Push the plan branch to origin to share it. This is the exposure
+                point: on a PUBLIC repo it prints a confirm heads-up + token and
+                exits; re-run with --confirm=<token>. --dry-run previews the
+                commits that would be pushed without pushing.
+
+Usage:
+  plan-branch <init|status|push> <repo> [--branch=<name>] [--confirm=<token>]
+                                        [--dry-run] [--json]
+"""
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from lib.config import (
+    load_config, ConfigError, DEFAULT_CONFIG_PATH, is_valid_git_repo,
+)
+from lib.git_state import is_safe_ref
+from lib.notes_readme import seed_readme
+from lib.prompts import parse_flags
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib import plan_worktree as pw
+
+_ACTIONS = ("init", "status", "push")
+_DEFAULT_BRANCH = "work-plan/plan"
+# A git refname segment: starts alnum, then alnum / . _ - and / separators. We
+# additionally reject `..`, leading/trailing `/`, and `//` below.
+_BRANCH_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+_KEY_RE = re.compile(r"^[A-Za-z0-9._-]+$")  # safe for the yq config path
+
+
+def _valid_branch(name: str) -> bool:
+    return (
+        is_safe_ref(name)
+        and bool(_BRANCH_RE.fullmatch(name))
+        and ".." not in name
+        and "//" not in name
+        and not name.startswith("/")
+        and not name.endswith("/")
+        and not name.endswith(".lock")
+    )
+
+
+def _set_plan_branch(key: str, branch: str) -> bool:
+    """Persist .repos.<key>.plan_branch=<branch> into config via yq. The branch
+    travels as an opaque env value (strenv), never interpolated. `key` is the
+    config repo key (validated by the caller). Returns True on success."""
+    env = {**os.environ, "WP_PLAN_BRANCH": branch}
+    expr = f".repos.{key}.plan_branch = strenv(WP_PLAN_BRANCH)"
+    try:
+        subprocess.run(
+            ["yq", "-i", expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True, env=env, timeout=20,
+        )
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return False
+    except (OSError, subprocess.TimeoutExpired) as e:
+        # yq missing / hung — degrade cleanly rather than crash with a traceback.
+        print(f"ERROR: could not run yq to update config: {e}")
+        return False
+
+
+def _resolve_repo(cfg: dict, repo_arg: Optional[str]):
+    """Return (key, entry, github, local_path) for a CONFIGURED repo, or print an
+    error and return None. plan-branch writes into a repo's config entry, so the
+    repo must be registered (init-repo) and have a local clone path."""
+    repos = cfg.get("repos") or {}
+    if repo_arg is None:
+        if len(repos) == 1:
+            key = next(iter(repos))
+        else:
+            print("ERROR: specify which repo — e.g. `plan-branch init <key>`. "
+                  f"Configured: {', '.join(repos) or '(none)'}.")
+            return None
+    elif repo_arg in repos:
+        key = repo_arg
+    else:
+        print(f"ERROR: '{repo_arg}' is not a configured repo. Register it first "
+              "with `init-repo <key> --github=org/repo --local=<path>`.")
+        return None
+
+    if not _KEY_RE.fullmatch(key):
+        print(f"ERROR: repo key '{key}' has unexpected characters; refusing to "
+              "edit config for it.")
+        return None
+    entry = repos[key] or {}
+    github = entry.get("github")
+    local_raw = entry.get("local")
+    if not local_raw:
+        print(f"ERROR: repo '{key}' has no local clone path in config. Add one "
+              f"with `init-repo {key} --github={github or 'org/repo'} --local=<path>`.")
+        return None
+    local_path = Path(local_raw).expanduser()
+    if not is_valid_git_repo(local_path):
+        print(f"ERROR: {local_path} is not a git repository.")
+        return None
+    return key, entry, github, local_path
+
+
+def _do_init(cfg, key, entry, github, local_path, flags) -> int:
+    raw = flags.get("--branch")
+    branch = raw if isinstance(raw, str) and raw else _DEFAULT_BRANCH
+    if not _valid_branch(branch):
+        print(f"ERROR: '{branch}' is not a valid branch name.")
+        return 2
+
+    existing = entry.get("plan_branch")
+    if existing and existing != branch:
+        print(f"ERROR: repo '{key}' already has plan_branch '{existing}'. "
+              "Refusing to silently switch it — edit config to change.")
+        return 1
+
+    # Fetch so the connect-vs-create decision sees a teammate's published branch.
+    pw.fetch_branch(local_path, branch)
+
+    if pw._branch_exists(local_path, branch):
+        # Connect: a branch already exists (local or origin) — reuse it.
+        wt = pw.ensure_worktree(local_path, branch)
+        if wt is None:
+            print(f"ERROR: branch '{branch}' exists but its worktree could not be "
+                  "created. Resolve any conflicting worktree and retry.")
+            return 1
+        # The branch already carries its own .work-plan/ — connecting just wires
+        # it up; no seeding (and no write into a possibly-absent dir).
+        print(f"✓ Connected repo '{key}' to existing plan branch '{branch}'.")
+        published = pw.is_published(local_path, branch)
+        print(f"  Source: {'origin (a teammate published it)' if published else 'local'}.")
+    else:
+        # Create a fresh orphan branch with only .work-plan/.
+        dest = pw.create_orphan_worktree(local_path, branch)
+        if dest is None:
+            print(f"ERROR: could not create the plan worktree for '{branch}'. "
+                  "Is there a stale worktree at the cache path, or no commits in "
+                  "the repo yet?")
+            return 1
+        seed_readme(dest / ".work-plan")
+        paths = pw.dirty_work_plan_paths(dest)
+        sha = pw.commit_shared_tier(
+            dest, f"work-plan: initialize plan branch {branch}", paths)
+        if sha is None:
+            print(f"ERROR: created the worktree but the initial commit failed.")
+            return 1
+        print(f"✓ Created orphan branch '{branch}' for '{key}' ({sha}, local only).")
+        print("  It holds only plan data — no shared history with your code, so "
+              "it won't appear in pull requests or deploys.")
+
+    if not _set_plan_branch(key, branch):
+        return 1
+    print(f"✓ Recorded plan_branch '{branch}' in config for '{key}'.")
+    print()
+    print("Next:")
+    print(f"  • Add a shared track:  /work-plan new-track {key} <slug>")
+    print(f"  • Share the branch:    /work-plan plan-branch push {key}")
+    if github and needs_confirm(github, cfg):
+        print(f"    ⚠ {github} is public — `push` will make the plan visible to anyone.")
+    return 0
+
+
+def _do_status(cfg, key, entry, github, local_path, flags) -> int:
+    branch = entry.get("plan_branch")
+    want_json = "--json" in flags
+    if not branch:
+        if want_json:
+            print(json.dumps({"repo": key, "plan_branch": None,
+                              "configured": False}))
+        else:
+            print(f"repo '{key}': no plan_branch configured.")
+            print(f"  Run `plan-branch init {key}` to set one up.")
+        return 0
+
+    pw.fetch_branch(local_path, branch)  # best-effort: accurate published/unpushed
+    local_exists = pw.local_branch_exists(local_path, branch)
+    published = pw.is_published(local_path, branch)
+    unpushed = pw.unpushed_oneline(local_path, branch)
+
+    if want_json:
+        print(json.dumps({
+            "repo": key, "plan_branch": branch, "configured": True,
+            "local_exists": local_exists, "published": published,
+            "unpushed_count": len(unpushed),
+        }))
+        return 0
+
+    print(f"repo '{key}': plan_branch '{branch}'")
+    print(f"  local branch: {'✓ present' if local_exists else '✗ missing (run init)'}")
+    print(f"  published:    {'✓ on origin' if published else '✗ local only — not shared yet'}")
+    if unpushed:
+        print(f"  unpushed:     {len(unpushed)} commit(s) — run "
+              f"`plan-branch push {key}` to share:")
+        for line in unpushed[:10]:
+            print(f"      {line}")
+        if len(unpushed) > 10:
+            print(f"      … and {len(unpushed) - 10} more")
+    else:
+        print("  unpushed:     none — origin is up to date.")
+    return 0
+
+
+def _do_push(cfg, key, entry, github, local_path, flags) -> int:
+    branch = entry.get("plan_branch")
+    if not branch:
+        print(f"ERROR: repo '{key}' has no plan_branch. Run `plan-branch init "
+              f"{key}` first.")
+        return 1
+    if not pw.local_branch_exists(local_path, branch):
+        print(f"ERROR: plan branch '{branch}' doesn't exist locally. Run "
+              f"`plan-branch init {key}` first.")
+        return 1
+
+    pw.fetch_branch(local_path, branch)
+    commits = pw.unpushed_oneline(local_path, branch)
+
+    if "--dry-run" in flags:
+        if not commits:
+            print(f"Nothing to push — origin/{branch} is up to date.")
+            return 0
+        print(f"Would push {len(commits)} commit(s) to origin/{branch}:")
+        for line in commits:
+            print(f"  {line}")
+        return 0
+
+    if not commits:
+        print(f"Nothing to push — origin/{branch} is up to date.")
+        return 0
+
+    # Exposure gate: publishing planning notes to a PUBLIC repo is a meaningful,
+    # effectively-permanent disclosure. Same confirm-token flow as other public
+    # writes, with concrete wording about what becomes visible. No `github and`
+    # short-circuit — needs_confirm() fails CLOSED on empty/unknown visibility,
+    # and that fail-closed behaviour must NOT be defeated (a config entry with a
+    # null/empty github would otherwise push unguarded).
+    if needs_confirm(github, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, github, branch)):
+            print(json.dumps({
+                "needs_confirm": True,
+                "reason": (
+                    f"{github} is PUBLIC (or its visibility is unknown). Pushing "
+                    f"'{branch}' makes your plan files — issue notes, priorities, "
+                    "and planning text — visible to anyone on the internet, and "
+                    "they remain in public git history even if the branch is "
+                    "later deleted."
+                ),
+                "token": make_token(github, branch),
+            }))
+            return 0
+
+    proc = pw.push_plan_branch(local_path, branch)
+    if proc is None:
+        print("ERROR: could not run git to push.")
+        return 1
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip()
+        if "protected" in err.lower() or "pull request" in err.lower():
+            print(f"ERROR: origin rejected the push — '{branch}' looks protected. "
+                  f"Exempt '{branch.split('/')[0]}/**' from PR/branch-protection "
+                  "rules for the plan branch, or push it manually once.")
+        else:
+            print(f"ERROR: push failed: {err or 'unknown git error'}")
+        return 1
+    print(f"✓ Pushed '{branch}' to origin ({len(commits)} commit(s)). "
+          "Teammates can `plan-branch init` to connect.")
+    return 0
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--branch", "--confirm", "--dry-run", "--json"})
+
+    action = positional[0] if positional else None
+    if action not in _ACTIONS:
+        print(f"usage: work_plan.py plan-branch <{'|'.join(_ACTIONS)}> <repo> "
+              "[--branch=<name>] [--confirm=<token>] [--dry-run] [--json]")
+        return 2
+
+    repo_arg = positional[1] if len(positional) > 1 else None
+
+    try:
+        cfg = load_config()
+    except (ConfigError, subprocess.CalledProcessError, OSError) as e:
+        # ConfigError is the expected case; CalledProcessError / OSError cover a
+        # malformed config or a missing `yq` so the command degrades to a clean
+        # error instead of a traceback (never-raise contract).
+        print(f"ERROR: could not load config: {e}")
+        return 1
+
+    resolved = _resolve_repo(cfg, repo_arg)
+    if resolved is None:
+        return 1
+    key, entry, github, local_path = resolved
+
+    if action == "init":
+        return _do_init(cfg, key, entry, github, local_path, flags)
+    if action == "status":
+        return _do_status(cfg, key, entry, github, local_path, flags)
+    return _do_push(cfg, key, entry, github, local_path, flags)

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}"