@stylusnexus/work-plan 2026.6.11 → 2026.6.13-2

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

@@ -0,0 +1,71 @@
+"""plan-ack — persist an acknowledgment into a plan/spec doc's YAML frontmatter
+(#286 slice 1).
+
+The VS Code viewer's default "Acknowledge (stop flagging)" persists in
+per-machine `workspaceState` — ephemeral and unshared. This command writes a
+durable `acknowledged: true` into the doc's **frontmatter only** (never the body,
+manifest, checkboxes, or status banner), so the acknowledgment is committed with
+the repo and shared with teammates. `plan-status` reads it back and demotes the
+doc the same way a local ack does.
+
+Usage:
+    work_plan.py plan-ack --repo=<key> [--confirm=<token>] -- <rel>
+    work_plan.py plan-ack --repo=<key> --clear [--confirm=<token>] -- <rel>
+
+`<rel>` is the repo-relative POSIX path of the plan doc (as emitted by
+`plan-status --json`); it is validated to resolve to a real file inside the repo.
+"""
+import sys
+
+from lib import config as config_mod
+from lib import plan_fm
+from lib.prompts import parse_flags
+
+KNOWN = {"--repo", "--clear", "--confirm"}
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print("ERROR: --repo=<key> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py plan-ack --repo=<key> [--clear] -- <rel>",
+              file=sys.stderr)
+        return 2
+    rel = positional[0]
+    clear = bool(flags.get("--clear"))
+
+    try:
+        cfg = config_mod.load_config()
+    except config_mod.ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    local = config_mod.resolve_local_path_for_folder(repo, cfg)
+    if not local or not local.exists():
+        print(f"repo '{repo}' has no resolvable local path in config", file=sys.stderr)
+        return 2
+
+    doc_path = plan_fm.resolve_doc_path(local, rel)
+    if doc_path is None:
+        print(f"ERROR: '{rel}' is not a file inside {local}", file=sys.stderr)
+        return 1
+
+    slug = config_mod.resolve_github_for_folder(repo, cfg)
+    action = "clearing the acknowledgment on" if clear else f"acknowledging '{rel}' via"
+    if not plan_fm.public_repo_gate(slug, rel, cfg, flags.get("--confirm"), action):
+        return 0
+
+    if clear:
+        if not plan_fm.set_key(doc_path, "acknowledged", None):
+            print(f"✓ {rel} was not acknowledged in frontmatter (nothing to clear).")
+            return 0
+        print(f"✓ cleared acknowledgment on {rel} (frontmatter only).")
+        return 0
+
+    plan_fm.set_key(doc_path, "acknowledged", True)
+    print(f"✓ {rel} acknowledged — wrote acknowledged:true to frontmatter only.")
+    return 0

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

@@ -0,0 +1,85 @@
+"""plan-baseline — stamp the CURRENT computed verdict into a plan/spec doc's YAML
+frontmatter as a drift baseline (#286 slice 2).
+
+Distinct from `plan-confirm` (a human *pin* that overrides the verdict) and from
+the body status banner (`plan-status --stamp`). This records `verdict_baseline:
+<computed>` so `plan-status` can later flag **drift** — when the live computed
+verdict diverges from the stamped baseline (e.g. a once-shipped plan whose
+declared files were deleted, silently regressing to partial). It is the third
+"started, then drifted off" signal the Plans view otherwise can't see.
+
+Frontmatter-only (never the body/manifest/checkboxes/banner). The baseline value
+is computed authoritatively here (the same evaluator plan-status uses), not taken
+from the caller.
+
+Usage:
+    work_plan.py plan-baseline --repo=<key> [--confirm=<token>] -- <rel>
+    work_plan.py plan-baseline --repo=<key> --clear [--confirm=<token>] -- <rel>
+"""
+import sys
+from datetime import date
+
+from lib import config as config_mod
+from lib import doc_discovery
+from lib import plan_fm
+from lib import verdict as verdict_mod
+from lib.prompts import parse_flags
+from commands.plan_status import evaluate_doc
+
+KNOWN = {"--repo", "--clear", "--confirm"}
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print("ERROR: --repo=<key> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py plan-baseline --repo=<key> [--clear] -- <rel>",
+              file=sys.stderr)
+        return 2
+    rel = positional[0]
+    clear = bool(flags.get("--clear"))
+
+    try:
+        cfg = config_mod.load_config()
+    except config_mod.ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    local = config_mod.resolve_local_path_for_folder(repo, cfg)
+    if not local or not local.exists():
+        print(f"repo '{repo}' has no resolvable local path in config", file=sys.stderr)
+        return 2
+
+    doc_path = plan_fm.resolve_doc_path(local, rel)
+    if doc_path is None:
+        print(f"ERROR: '{rel}' is not a file inside {local}", file=sys.stderr)
+        return 1
+
+    slug = config_mod.resolve_github_for_folder(repo, cfg)
+    action = "clearing the verdict baseline on" if clear else f"stamping a verdict baseline on '{rel}' via"
+    if not plan_fm.public_repo_gate(slug, rel, cfg, flags.get("--confirm"), action):
+        return 0
+
+    if clear:
+        if not plan_fm.set_key(doc_path, "verdict_baseline", None):
+            print(f"✓ {rel} had no verdict baseline (nothing to clear).")
+            return 0
+        print(f"✓ cleared verdict baseline on {rel} (frontmatter only).")
+        return 0
+
+    # Compute the verdict authoritatively (same evaluator plan-status uses).
+    doc = doc_discovery.Doc(path=doc_path, rel=rel,
+                            kind=doc_discovery.classify_kind(rel))
+    cfg_stall = cfg.get("stall_days")
+    stall_days = cfg_stall if isinstance(cfg_stall, int) else verdict_mod.STALL_DAYS
+    row = evaluate_doc(doc, local, date.today(), verdict_mod.DEAD_DAYS, stall_days)
+    verdict = row["verdict"]
+
+    plan_fm.set_key(doc_path, "verdict_baseline", verdict)
+    print(f"✓ {rel} baseline stamped at '{verdict}' — wrote verdict_baseline to "
+          f"frontmatter only. plan-status will flag drift if the live verdict changes.")
+    return 0

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

@@ -0,0 +1,83 @@
+"""plan-confirm — write a human `verdict_override` into a plan/spec doc's YAML
+frontmatter (#286).
+
+This is the one viewer-driven write to a plan doc, and it is **frontmatter-only**
+by hard constraint: it touches the doc's YAML frontmatter and nothing else — never
+the prose body, the declared-file manifest, the checkboxes, or the status banner.
+A reviewer uses it to affirm a verdict the mechanical heuristic got wrong (e.g. a
+genuinely-shipped plan whose phase checkboxes were never ticked), which silences
+the "shipped but boxes unchecked" lie-gap on the next `plan-status` read.
+
+Usage:
+    work_plan.py plan-confirm --repo=<key> --verdict=shipped|partial|dead [--confirm=<token>] -- <rel>
+    work_plan.py plan-confirm --repo=<key> --clear [--confirm=<token>] -- <rel>
+
+`<rel>` is the repo-relative POSIX path of the plan doc (as emitted by
+`plan-status --json`). It is validated to resolve to a real file inside the repo,
+so a caller can't redirect the write outside the checkout.
+"""
+import sys
+
+from lib import config as config_mod
+from lib import plan_fm
+from lib.prompts import parse_flags
+
+VALID_VERDICTS = {"shipped", "partial", "dead"}
+KNOWN = {"--repo", "--verdict", "--clear", "--confirm"}
+
+
+def run(args: list) -> int:
+    flags, positional = parse_flags(args, KNOWN)
+
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        print("ERROR: --repo=<key> is required.", file=sys.stderr)
+        return 2
+    if not positional:
+        print("usage: work_plan.py plan-confirm --repo=<key> "
+              "--verdict=shipped|partial|dead [--clear] -- <rel>", file=sys.stderr)
+        return 2
+    rel = positional[0]
+
+    clear = bool(flags.get("--clear"))
+    verdict = flags.get("--verdict")
+    if not clear:
+        if not verdict or verdict is True or verdict not in VALID_VERDICTS:
+            print("ERROR: --verdict must be one of shipped|partial|dead "
+                  "(or pass --clear to remove the override).", file=sys.stderr)
+            return 2
+
+    try:
+        cfg = config_mod.load_config()
+    except config_mod.ConfigError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    local = config_mod.resolve_local_path_for_folder(repo, cfg)
+    if not local or not local.exists():
+        print(f"repo '{repo}' has no resolvable local path in config", file=sys.stderr)
+        return 2
+
+    doc_path = plan_fm.resolve_doc_path(local, rel)
+    if doc_path is None:
+        print(f"ERROR: '{rel}' is not a file inside {local}", file=sys.stderr)
+        return 1
+
+    # Public-repo confirm gate (the extension surfaces this as a modal). The token
+    # is keyed on (slug, rel) — the same shape close/set use, so the viewer's
+    # existing executeWrite token flow drives it unchanged.
+    slug = config_mod.resolve_github_for_folder(repo, cfg)
+    action = "clearing the verdict override on" if clear else f"marking '{rel}' as {verdict} via"
+    if not plan_fm.public_repo_gate(slug, rel, cfg, flags.get("--confirm"), action):
+        return 0
+
+    if clear:
+        if not plan_fm.set_key(doc_path, "verdict_override", None):
+            print(f"✓ no verdict override on {rel} (nothing to clear).")
+            return 0
+        print(f"✓ cleared verdict override on {rel} (frontmatter only).")
+        return 0
+
+    plan_fm.set_key(doc_path, "verdict_override", verdict)
+    print(f"✓ {rel} confirmed {verdict} — wrote verdict_override to frontmatter only.")
+    return 0