@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,128 @@
+"""hygiene subcommand: weekly cleanup wrapper.
+
+Runs in sequence:
+  1. refresh-md --all --yes  (drift in body status tables)
+  2. reconcile --all          (sync track/<slug> labels ↔ frontmatter)
+  3. duplicates               (find consolidation candidates)
+
+One command for the standard weekly maintenance pass.
+
+Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 3 (duplicates)
+is per-repo, so:
+  - when --repo is set, it's scoped to that repo;
+  - when --repo is absent and config has exactly one repo, it runs against
+    that repo;
+  - when --repo is absent and config has multiple repos, it's skipped cleanly
+    (rather than letting duplicates exit non-zero on the ambiguous case).
+
+Pass --timeout=N to set the gh subprocess timeout for the duplicates step
+(default 30s).
+"""
+from commands import refresh_md, reconcile, duplicates
+from lib.config import load_config, ConfigError
+from lib.prompts import parse_flags
+import time
+
+
+def _resolve_repo_folder(repo_key: str, cfg: dict):
+    """Translate hygiene's --repo arg (folder key OR org/repo slug) to a config
+    folder key, which is what duplicates expects. Returns None if unresolvable.
+    """
+    repos = cfg.get("repos", {})
+    if repo_key in repos:
+        return repo_key
+    k = repo_key.lower()
+    for folder, entry in repos.items():
+        if entry.get("github", "").lower() == k:
+            return folder
+    return None
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--yes", "--no-duplicates", "--repo", "--timeout"})
+    skip_dups = flags.get("--no-duplicates", False)
+    yes = flags.get("--yes", False)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>] [--timeout=N]")
+        return 2
+
+    gh_timeout = None
+    raw_timeout = flags.get("--timeout")
+    if raw_timeout is not None and raw_timeout is not True:
+        try:
+            gh_timeout = int(raw_timeout)
+        except ValueError:
+            print(f"WARNING: invalid --timeout value '{raw_timeout}'; using default")
+    elif raw_timeout is True:
+        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>] [--timeout=N]")
+        return 2
+
+    scope_label = f" --repo={repo_key}" if repo_key else " --all"
+
+    t0 = time.time()
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 1 of 3: refresh-md{scope_label}")
+    print("=" * 60)
+    refresh_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
+    if yes:
+        refresh_args.append("--yes")
+    rc = refresh_md.run(refresh_args)
+    if rc != 0:
+        print(f"\n⚠ refresh-md exited with code {rc}; continuing.")
+    print(f"  (step 1/3 done in {time.time() - t0:.1f}s)")
+
+    t1 = time.time()
+    print()
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 2 of 3: reconcile{scope_label}")
+    print("=" * 60)
+    reconcile_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
+    rc = reconcile.run(reconcile_args)
+    if rc != 0:
+        print(f"\n⚠ reconcile exited with code {rc}; continuing.")
+    print(f"  (step 2/3 done in {time.time() - t1:.1f}s)")
+
+    if skip_dups:
+        print()
+        print("(skipping duplicates per --no-duplicates)")
+        return 0
+
+    t2 = time.time()
+    print()
+    print("=" * 60)
+    print("WEEKLY HYGIENE — step 3 of 3: duplicates")
+    print("=" * 60)
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"⚠ could not load config for duplicates step: {e}")
+        return 0
+
+    dupes_args: list[str] = []
+    repos = cfg.get("repos", {})
+    if repo_key:
+        folder = _resolve_repo_folder(repo_key, cfg)
+        if folder is None:
+            print(f"(skipping duplicates: --repo={repo_key} not found in config.yml)")
+            return 0
+        dupes_args = [f"--repo={folder}"]
+    elif len(repos) > 1:
+        print("(skipping duplicates: multiple repos in config and no --repo passed.")
+        print(" run `/work-plan duplicates --repo=<folder-name>` per repo to scan them.)")
+        return 0
+    # else: 0 or 1 repos → duplicates handles both (errors / single-repo auto-pick)
+
+    if gh_timeout is not None:
+        dupes_args.append(f"--timeout={gh_timeout}")
+
+    rc = duplicates.run(dupes_args)
+    if rc != 0:
+        print(f"\n⚠ duplicates exited with code {rc}.")
+    print(f"  (step 3/3 done in {time.time() - t2:.1f}s)")
+
+    print()
+    print(f"✓ Weekly hygiene complete ({time.time() - t0:.1f}s total). Review the duplicate candidates above and "
+          "consolidate any real dupes via `gh issue close`.")
+    return 0

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

@@ -0,0 +1,128 @@
+"""init subcommand — non-interactive, flag-driven."""
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from lib.config import load_config, ConfigError, resolve_github_for_folder
+from lib.frontmatter import parse_file, write_file
+from lib.prompts import parse_flags
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+_VALID_PRIORITIES = {"P0", "P1", "P2", "P3"}
+
+
+def _find_repo_for_shared_path(path: Path, cfg: dict) -> Optional[str]:
+    """If path is inside a .work-plan/ dir, find the configured github repo for that clone."""
+    # Walk up the path looking for a .work-plan ancestor
+    for parent in path.parents:
+        if parent.name == ".work-plan":
+            clone_root = parent.parent
+            for folder, entry in cfg.get("repos", {}).items():
+                if entry.get("local"):
+                    local = Path(entry["local"]).expanduser().resolve()
+                    if local == clone_root.resolve():
+                        return entry.get("github")
+            return None  # In .work-plan/ but not registered
+    return None  # Not in a .work-plan/
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--priority", "--milestone", "--confirm"})
+
+    if not positional:
+        print("usage: work_plan.py init <path-to-md>")
+        return 2
+
+    path = Path(positional[0]).expanduser().resolve()
+    if not path.exists():
+        print(f"ERROR: file not found: {path}")
+        return 1
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    meta, body = parse_file(path)
+    if meta:
+        print(f"{path.name} already has frontmatter.")
+        return 0
+
+    slug = re.sub(r"[^a-z0-9-]+", "-", path.stem.lower()).strip("-")
+
+    # Detect if this path is inside a .work-plan/ shared directory
+    is_shared = ".work-plan" in path.parts
+    tier = "shared" if is_shared else None
+
+    if is_shared:
+        repo = _find_repo_for_shared_path(path, cfg)
+        if repo is None:
+            print(
+                "ERROR: path is inside a .work-plan/ directory but its repo isn't"
+                " registered in config — run init-repo first"
+            )
+            return 1
+        folder = None
+    else:
+        notes_root = Path(cfg["notes_root"])
+        try:
+            rel = path.relative_to(notes_root)
+            folder = rel.parts[0] if len(rel.parts) > 1 else None
+        except ValueError:
+            folder = 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)))
+
+    # Resolve priority — default P2; invalid value falls back to P2
+    raw_priority = flags.get("--priority")
+    if isinstance(raw_priority, str):
+        priority = raw_priority.upper()
+        if priority not in _VALID_PRIORITIES:
+            priority = "P2"
+    else:
+        priority = "P2"
+
+    # Resolve milestone — default v1.0.0
+    milestone_flag = flags.get("--milestone")
+    milestone = milestone_flag if isinstance(milestone_flag, str) else "v1.0.0"
+
+    # Confirm-token gate — only for real resolvable repos (not TBD/unknown).
+    # Checked before printing the info block so the gate output is the only
+    # stdout (the extension surfaces this as a modal, JSON-parse the first line).
+    if repo and repo != "TBD" and needs_confirm(repo, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, repo, slug)):
+            print(json.dumps({
+                "needs_confirm": True,
+                "reason": (
+                    f"{repo} is PUBLIC (or visibility unknown); "
+                    f"the new track '{slug}' references it."
+                ),
+                "token": make_token(repo, slug),
+            }))
+            return 0
+
+    print(f"Initializing: {path.name}")
+    print(f"  track: {slug}")
+    print(f"  repo: {repo or '(unknown — will set TBD)'}")
+    if tier == "shared":
+        print("  tier: shared")
+    print(f"  issues found in body: {issue_nums or '(none)'}")
+
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M")
+    meta = {
+        "track": slug, "status": "active",
+        "launch_priority": priority,
+        "milestone_alignment": milestone,
+        "github": {"repo": repo or "TBD", "issues": issue_nums, "branches": []},
+        "related_tracks": [],
+        "last_touched": now, "last_handoff": now,
+        "next_up": [], "blockers": [],
+    }
+    write_file(path, meta, body)
+    print(f"✓ Frontmatter added to {path.name}.")
+    return 0

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

@@ -0,0 +1,132 @@
+"""init-repo subcommand — bootstrap a new repo block + notes folder.
+
+Non-interactive: --github is required; --local is optional (no prompts).
+"""
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from lib.config import load_config, ConfigError, DEFAULT_CONFIG_PATH, is_valid_git_repo
+from lib.prompts import parse_flags
+
+
+def _count_shared_tracks(work_plan_dir: Path) -> int:
+    """Count eligible .md files in a .work-plan/ directory.
+
+    Excludes: README.md, dotfiles, and anything inside archive/.
+    """
+    count = 0
+    for p in work_plan_dir.iterdir():
+        if p.is_dir():
+            continue
+        if p.name.startswith("."):
+            continue
+        if p.name.lower() == "readme.md":
+            continue
+        if p.suffix == ".md":
+            count += 1
+    return count
+
+
+def _report_shared_tracks(local_path: "Path | None") -> None:
+    """Print a status line about shared tracks found in .work-plan/ (if any).
+
+    If local_path is None, not a valid git repo, or has no .work-plan/ dir,
+    prints the registration-only fallback message instead.
+    """
+    if local_path is None or not is_valid_git_repo(local_path):
+        print()
+        print("ℹ No valid local clone provided — registered for future use.")
+        print("  Run 'work-plan init-repo <key> --local=<path>' to add the clone path later.")
+        return
+    work_plan_dir = local_path / ".work-plan"
+    if work_plan_dir.is_dir():
+        n = _count_shared_tracks(work_plan_dir)
+        print(
+            f"ℹ Found {n} shared track(s) in {work_plan_dir}/"
+            " — they'll appear after 'work-plan brief'."
+        )
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--github", "--local"})
+    if not positional:
+        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>]")
+        return 2
+
+    key = positional[0]
+    if not re.fullmatch(r"[a-z][a-z0-9-]*", key):
+        print(f"ERROR: '{key}' is not a valid key. Use lowercase letters, digits, hyphens; must start with a letter.")
+        return 2
+
+    # --github is required; no prompt fallback
+    github = flags.get("--github")
+    if not github or "/" not in github:
+        if not github:
+            print("ERROR: --github is required (e.g. --github=org/repo).")
+        else:
+            print("ERROR: github slug must be in the form 'org/repo'.")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        print("\nRun ./install.sh from the toolkit root to seed your config first.")
+        return 1
+
+    if key in cfg.get("repos", {}):
+        print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
+        print("Edit it manually, or pick a different key.")
+        return 1
+
+    # --local is optional; if absent, skip (no prompt)
+    local = flags.get("--local") or None
+    local_path = None
+    if local:
+        local_path = Path(local).expanduser()
+        if not local_path.exists():
+            print(f"WARN: {local_path} does not exist. Saving anyway — fix later if wrong.")
+
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if not notes_root.exists():
+        print(f"ERROR: notes_root {notes_root} does not exist.")
+        print("Fix the path in ~/.claude/work-plan/config.yml or create the directory.")
+        return 1
+
+    repo_dir = notes_root / key
+    archive_shipped = repo_dir / "archive" / "shipped"
+    archive_abandoned = repo_dir / "archive" / "abandoned"
+    archive_shipped.mkdir(parents=True, exist_ok=True)
+    archive_abandoned.mkdir(parents=True, exist_ok=True)
+    (archive_shipped / ".gitkeep").touch()
+    (archive_abandoned / ".gitkeep").touch()
+    print(f"✓ Created notes folder: {repo_dir}/")
+    print(f"  ├── archive/shipped/")
+    print(f"  └── archive/abandoned/")
+
+    # Detect existing shared tracks in .work-plan/ inside the local clone
+    _report_shared_tracks(local_path)
+
+    repo_block = {"github": github}
+    if local:
+        repo_block["local"] = local
+
+    yq_expr = f'.repos.{key} = {json.dumps(repo_block)}'
+    try:
+        subprocess.run(
+            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return 1
+    print(f"✓ Added repo '{key}' to {DEFAULT_CONFIG_PATH}")
+
+    print()
+    print("Next steps:")
+    print(f"  • Add a track:        /work-plan init '{repo_dir}/<track-slug>.md'")
+    print(f"  • AI-cluster issues:  /work-plan group --repo={key} --milestone=v1.0.0")
+    print(f"  • See it listed:      /work-plan list")
+    return 0

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

@@ -0,0 +1,39 @@
+"""list subcommand."""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, discover_archived_tracks
+
+
+def run(args: list[str]) -> int:
+    show_all = "--all" in args
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    if not tracks and not show_all:
+        print(f"No tracks found under {cfg['notes_root']}")
+        return 0
+
+    print(f"Tracks under {cfg['notes_root']}:\n")
+    for t in tracks:
+        status = t.meta.get("status", "(no frontmatter)")
+        priority = t.meta.get("launch_priority", "—")
+        repo = t.repo or "(no repo)"
+        flags = []
+        if t.needs_init:
+            flags.append("NEEDS INIT")
+        if t.needs_filing:
+            flags.append("NEEDS FILING")
+        flag_str = f" [{', '.join(flags)}]" if flags else ""
+        print(f"  {t.name:30}  {status:14}  {priority:3}  {repo}{flag_str}")
+
+    if show_all:
+        archived = discover_archived_tracks(cfg)
+        if archived:
+            print("\nArchived:")
+            for a in archived:
+                end_state = a.meta.get("status", "?")
+                print(f"  {a.name:30}  {end_state:14}  {a.repo or '(no repo)'}")
+    return 0

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

@@ -0,0 +1,225 @@
+"""new-track subcommand — one-shot non-interactive track creation.
+
+Creates a brand-new <slug>.md under notes_root/<folder>/ (private tier) or
+<local>/.work-plan/ (shared tier) with frontmatter written from flags.
+Designed for headless callers (e.g. the VS Code extension) that cannot run
+interactive init + do not know notes_root upfront.
+
+Usage:
+  new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]
+                          [--private] [--commit] [--confirm=<token>]
+"""
+import json
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from lib.config import load_config, ConfigError, is_valid_git_repo
+from lib.frontmatter import write_file
+from lib.prompts import parse_flags
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+_VALID_PRIORITIES = {"P0", "P1", "P2", "P3"}
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def _git_commit_track(track_file: Path, slug: str) -> None:
+    """Stage and commit a single shared track file (path-scoped, no git add .)."""
+    # The clone root is .work-plan/'s parent
+    clone_root = track_file.parent.parent
+    if not is_valid_git_repo(clone_root):
+        print(f"⚠ --commit ignored: track is private (not in a git repo)")
+        return
+
+    # Determine current branch name for the success message
+    branch = "HEAD"
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(clone_root), "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True, text=True, check=False,
+        )
+        if result.returncode == 0:
+            branch = result.stdout.strip()
+    except OSError:
+        pass
+
+    # Stage ONLY this file (never git add .)
+    try:
+        subprocess.run(
+            ["git", "-C", str(clone_root), "add", str(track_file)],
+            capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as e:
+        msg = getattr(e, "stderr", str(e))
+        print(f"⚠ --commit: git add failed ({msg.strip()!r}) — continuing without commit")
+        return
+
+    # Commit with a conventional message
+    commit_msg = f"chore: add shared track '{slug}'"
+    try:
+        subprocess.run(
+            ["git", "-C", str(clone_root), "commit", "-m", commit_msg],
+            capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as e:
+        msg = getattr(e, "stderr", str(e))
+        print(f"⚠ --commit: git commit failed ({msg.strip()!r}) — continuing without commit")
+        return
+
+    print(f"✓ committed '{slug}' to {branch}")
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--priority", "--milestone", "--private", "--confirm", "--commit"}
+    )
+
+    # Require exactly 2 positionals: repo and slug
+    if len(positional) < 2:
+        print(
+            "usage: work_plan.py new-track <repo> <slug>"
+            " [--priority=P0..P3] [--milestone=<m>] [--private] [--commit]"
+            " [--confirm=<token>]"
+        )
+        return 2
+
+    repo_arg = positional[0]
+    slug = positional[1]
+
+    # ------------------------------------------------------------------
+    # Resolve repo + folder from the repo argument
+    # ------------------------------------------------------------------
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    if repo_arg in cfg.get("repos", {}):
+        github = cfg["repos"][repo_arg]["github"]
+        folder = repo_arg
+    elif "/" in repo_arg:
+        github = repo_arg
+        folder = repo_arg.rsplit("/", 1)[-1]
+    else:
+        print(
+            f"ERROR: unknown repo '{repo_arg}' — pass a configured key"
+            " or an org/repo slug"
+        )
+        return 1
+
+    # ------------------------------------------------------------------
+    # Validate slug: lowercase letters / digits / hyphens, starts with letter
+    # ------------------------------------------------------------------
+    if not _SLUG_RE.fullmatch(slug):
+        print(
+            f"ERROR: '{slug}' is not a valid slug."
+            " Use lowercase letters, digits, hyphens; must start with a letter."
+        )
+        return 2
+
+    # ------------------------------------------------------------------
+    # Resolve priority (default P2, invalid → P2) and milestone (default v1.0.0)
+    # ------------------------------------------------------------------
+    raw_priority = flags.get("--priority")
+    if isinstance(raw_priority, str):
+        priority = raw_priority.upper()
+        if priority not in _VALID_PRIORITIES:
+            priority = "P2"
+    else:
+        priority = "P2"
+
+    milestone_flag = flags.get("--milestone")
+    milestone = milestone_flag if isinstance(milestone_flag, str) else "v1.0.0"
+
+    # ------------------------------------------------------------------
+    # Determine target path: shared (.work-plan/) or private (notes_root/)
+    # Shared route: repo is registered, has a local path, and it's a valid git repo.
+    # --private overrides to force the private (notes_root) route.
+    # ------------------------------------------------------------------
+    use_private = "--private" in flags
+
+    shared_path: Optional[Path] = None
+    if not use_private and folder in cfg.get("repos", {}):
+        local_raw = cfg["repos"][folder].get("local")
+        if local_raw:
+            local_path = Path(local_raw).expanduser()
+            if is_valid_git_repo(local_path):
+                shared_path = local_path / ".work-plan" / f"{slug}.md"
+
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if shared_path is not None:
+        path = shared_path
+        is_shared = True
+    else:
+        if not notes_root.exists():
+            print(f"ERROR: notes_root {notes_root} does not exist.")
+            return 1
+        path = notes_root / folder / f"{slug}.md"
+        is_shared = False
+
+    if path.exists():
+        print(f"ERROR: track '{slug}' already exists at {path}")
+        return 2
+
+    # ------------------------------------------------------------------
+    # Confirm-token gate (BEFORE creating anything)
+    # Mirror the exact JSON shape used by init/slot/close/set.
+    # ------------------------------------------------------------------
+    if needs_confirm(github, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, github, slug)):
+            print(json.dumps({
+                "needs_confirm": True,
+                "reason": (
+                    f"{github} is PUBLIC (or visibility unknown); "
+                    f"the new track '{slug}' will be written there."
+                ),
+                "token": make_token(github, slug),
+            }))
+            return 0
+
+    # ------------------------------------------------------------------
+    # Create folder if missing, then write the track file
+    # ------------------------------------------------------------------
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M")
+    meta = {
+        "track": slug,
+        "status": "active",
+        "launch_priority": priority,
+        "milestone_alignment": milestone,
+        "github": {"repo": github, "issues": [], "branches": []},
+        "related_tracks": [],
+        "last_touched": now,
+        "last_handoff": now,
+        "next_up": [],
+        "blockers": [],
+    }
+    if is_shared:
+        meta["tier"] = "shared"
+
+    body = f"# {slug}\n"
+    write_file(path, meta, body)
+
+    if is_shared:
+        print(f"✓ Created shared track '{slug}' for {github} at {path}")
+    else:
+        rel = path.relative_to(notes_root)
+        print(f"✓ Created track '{slug}' for {github} at {rel}")
+
+    # ------------------------------------------------------------------
+    # --commit: stage + commit the track file to the shared repo (non-fatal)
+    # Only meaningful for shared tracks; warn and skip for private.
+    # ------------------------------------------------------------------
+    want_commit = "--commit" in flags
+    if want_commit:
+        if is_shared:
+            _git_commit_track(path, slug)
+        else:
+            print("⚠ --commit ignored: track is private (not in a git repo)")
+
+    return 0