@stylusnexus/work-plan 2026.6.9

package/skills/work-plan/lib/closure.py

@@ -0,0 +1,72 @@
+"""Closure-ready signal detection."""
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+from lib.git_state import last_commit_date, branch_exists
+
+
+@dataclass
+class ClosureSignals:
+    """The 5 closure signals from the spec."""
+    all_issues_closed: bool
+    all_branches_done: bool
+    next_up_empty: bool
+    cold_14d: bool
+    no_recent_related_issues: bool
+
+
+def is_closure_ready(signals: ClosureSignals) -> tuple[bool, list[str]]:
+    """All signals must be true. Returns (ready, blocking-reasons)."""
+    reasons = []
+    if not signals.all_issues_closed:
+        reasons.append("open issues remain")
+    if not signals.all_branches_done:
+        reasons.append("branches still active")
+    if not signals.next_up_empty:
+        reasons.append("next_up is not empty")
+    if not signals.cold_14d:
+        reasons.append("recent commits within 14 days")
+    if not signals.no_recent_related_issues:
+        reasons.append("new related issues in last 30 days")
+    return (not reasons, reasons)
+
+
+def compute_signals(track_meta: dict, github_issues: list[dict],
+                    repo_path: Optional[Path],
+                    recent_related_count: int) -> ClosureSignals:
+    """Build ClosureSignals from observed state."""
+    listed_issue_nums = track_meta.get("github", {}).get("issues") or []
+    state_by_num = {i["number"]: i.get("state", "OPEN") for i in github_issues}
+
+    all_closed = bool(listed_issue_nums) and all(
+        state_by_num.get(n, "OPEN") == "CLOSED" for n in listed_issue_nums
+    )
+
+    branches = track_meta.get("github", {}).get("branches") or []
+    if repo_path:
+        all_branches_done = all(not branch_exists(b, repo_path) for b in branches)
+    else:
+        all_branches_done = len(branches) == 0
+
+    next_up_empty = not (track_meta.get("next_up") or [])
+
+    cutoff = datetime.now() - timedelta(days=14)
+    cold = True
+    if repo_path:
+        for b in branches:
+            last = last_commit_date(b, repo_path)
+            if last and last > cutoff:
+                cold = False
+                break
+
+    no_recent = recent_related_count == 0
+
+    return ClosureSignals(
+        all_issues_closed=all_closed,
+        all_branches_done=all_branches_done,
+        next_up_empty=next_up_empty,
+        cold_14d=cold,
+        no_recent_related_issues=no_recent,
+    )

package/skills/work-plan/lib/config.py

@@ -0,0 +1,82 @@
+"""Load + validate ~/.claude/work-plan/config.yml."""
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_CONFIG_PATH = Path.home() / ".claude" / "work-plan" / "config.yml"
+DEFAULT_NOTES_ROOT = Path.home() / ".claude" / "work-plan" / "notes"
+
+_SEED_TEMPLATE = (
+    "# work-plan config — auto-seeded on first run. Edit to customize.\n"
+    "# Run /work-plan init-repo <key> --github=<org/repo> to populate repos:.\n"
+    "notes_root: {notes_root}\n"
+    "repos: {{}}\n"
+)
+
+
+class ConfigError(Exception):
+    pass
+
+
+def ensure_config(path: Path = DEFAULT_CONFIG_PATH,
+                  notes_root: Path = DEFAULT_NOTES_ROOT) -> bool:
+    """Create a default config.yml (and notes_root dir) if absent.
+
+    Single source of the seed content — install.sh/install.ps1 delegate here, so
+    plugin installs (which run no install hook) and script installs behave
+    identically. `notes_root` is written as an ABSOLUTE path (never a literal
+    `~`, which downstream `Path(...)` would not expand). Returns True if it
+    created the file, False if it already existed.
+    """
+    path = Path(path)
+    if path.exists():
+        return False
+    notes_root = Path(notes_root).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    notes_root.mkdir(parents=True, exist_ok=True)
+    path.write_text(_SEED_TEMPLATE.format(notes_root=notes_root), encoding="utf-8")
+    return True
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH,
+                notes_root: Path = DEFAULT_NOTES_ROOT) -> dict:
+    """Load and validate. Self-seeds a default config if absent (no install hook
+    exists for plugin installs). Normalizes string-shape repo entries to dicts."""
+    path = Path(path)
+    if not path.exists():
+        ensure_config(path, notes_root)
+    text = path.read_text(encoding="utf-8")
+    proc = subprocess.run(
+        ["yq", "-o=json", "."], input=text,
+        capture_output=True, text=True, check=True,
+    )
+    cfg = json.loads(proc.stdout)
+    if not isinstance(cfg, dict):
+        raise ConfigError(f"config.yml must be a YAML mapping; got {type(cfg).__name__}")
+    if "notes_root" not in cfg:
+        raise ConfigError("config.yml missing required key 'notes_root'.")
+    cfg.setdefault("repos", {})
+    # Normalize string-shape entries to dict shape
+    for folder, val in list(cfg["repos"].items()):
+        if isinstance(val, str):
+            cfg["repos"][folder] = {"github": val, "local": None}
+        elif isinstance(val, dict):
+            val.setdefault("local", None)
+            if "github" not in val:
+                raise ConfigError(f"repo '{folder}' missing 'github' key")
+        else:
+            raise ConfigError(f"repo '{folder}' must be string or dict, got {type(val).__name__}")
+    return cfg
+
+
+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
+
+
+def resolve_local_path_for_folder(folder_name: str, cfg: dict) -> Optional[Path]:
+    entry = cfg.get("repos", {}).get(folder_name)
+    if not entry or not entry.get("local"):
+        return None
+    return Path(entry["local"]).expanduser()

package/skills/work-plan/lib/doc_discovery.py

@@ -0,0 +1,41 @@
+"""Discover plan/spec docs in a repo via configurable globs, and classify each."""
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_GLOBS = [
+    "docs/superpowers/plans/*.md",
+    "docs/superpowers/specs/*.md",
+    "docs/plans/*.md",
+]
+
+
+@dataclass
+class Doc:
+    path: Path   # absolute
+    rel: str     # repo-relative POSIX-style
+    kind: str    # "plan" | "spec" | "adhoc"
+
+
+def classify_kind(rel: str) -> str:
+    """Heuristic doc-kind from its repo-relative path."""
+    if rel.endswith("-design.md") or "/specs/" in rel:
+        return "spec"
+    if "/plans/" in rel:
+        return "plan"
+    return "adhoc"
+
+
+def discover_docs(repo_root: Path, globs: Optional[list] = None) -> list:
+    globs = globs or DEFAULT_GLOBS
+    repo_root = Path(repo_root)
+    out = []
+    seen = set()
+    for g in globs:
+        for p in sorted(repo_root.glob(g)):
+            if not p.is_file() or p in seen:
+                continue
+            seen.add(p)
+            rel = p.relative_to(repo_root).as_posix()
+            out.append(Doc(path=p, rel=rel, kind=classify_kind(rel)))
+    return out

package/skills/work-plan/lib/drift.py

@@ -0,0 +1,32 @@
+"""Detect drift between body status table and GitHub state."""
+from lib.status_table import find_status_table, ISSUE_NUM_RE
+
+
+def detect_drift(body: str, github_issues: list[dict]) -> list[dict]:
+    """Return list of {issue, body_status, github_state} for drifted rows."""
+    table = find_status_table(body)
+    if not table:
+        return []
+
+    state_by_num = {i["number"]: i.get("state", "OPEN") for i in github_issues}
+    drift = []
+    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))
+        if not nums:
+            continue
+        body_status = row["cells"][sidx].strip().lower() if sidx < len(row["cells"]) else ""
+        for num in nums:
+            if num not in state_by_num:
+                continue
+            gh_state = state_by_num[num]
+            looks_closed = any(k in body_status for k in ("✅", "shipped", "merged", "closed"))
+            looks_open = "🔲" in body_status or "open" in body_status
+
+            if gh_state == "CLOSED" and not looks_closed:
+                drift.append({"issue": num, "body_status": body_status, "github_state": "CLOSED"})
+            elif gh_state == "OPEN" and looks_closed:
+                drift.append({"issue": num, "body_status": body_status, "github_state": "OPEN"})
+    return drift

package/skills/work-plan/lib/export_model.py

@@ -0,0 +1,40 @@
+"""Build the versioned viewer export structure from tracks + fetched issues."""
+from lib.github_state import format_assignees, short_milestone
+
+SCHEMA = 1
+
+def _issue(i: dict) -> dict:
+    state = (i.get("state") or "OPEN").lower()
+    return {
+        "number": i.get("number"),
+        "title": i.get("title", ""),
+        "state": "closed" if state in ("closed", "merged") else "open",
+        "assignee": (format_assignees(i) if i.get("assignees") else "—"),
+        "milestone": short_milestone(i.get("milestone")) or None,
+    }
+
+def build_export(tracks, issues_by_track, visibility, now: str,
+                 untracked_by_repo=None) -> dict:
+    out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
+    for t in tracks:
+        issues = [_issue(i) for i in issues_by_track.get(t.name, [])]
+        opened = sum(1 for i in issues if i["state"] == "open")
+        out["tracks"].append({
+            "name": t.name,
+            "repo": t.repo,
+            "tier": getattr(t, "tier", "private") or "private",
+            "status": t.meta.get("status"),
+            "launch_priority": t.meta.get("launch_priority"),
+            "milestone_alignment": t.meta.get("milestone_alignment"),
+            "visibility": visibility.get(t.repo),
+            "blockers": list(t.meta.get("blockers") or []),
+            "next_up": list(t.meta.get("next_up") or []),
+            "rollup": {"open": opened, "closed": len(issues) - opened},
+            "issues": issues,
+        })
+    out["untracked"] = [
+        {"repo": repo, "issues": [_issue(r) for r in rows]}
+        for repo, rows in (untracked_by_repo or {}).items()
+        if rows
+    ]
+    return out

package/skills/work-plan/lib/frontmatter.py

@@ -0,0 +1,48 @@
+"""Parse + write YAML frontmatter on markdown files. Body-preserving."""
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Tuple
+
+# Use [ \t]* (not \s*) so horizontal-only whitespace is consumed after ---,
+# preserving any leading newline that is part of the body.
+FRONTMATTER_RE = re.compile(r"^---[ \t]*\n(.*?)\n---[ \t]*\n(.*)$", re.DOTALL)
+
+
+def parse_file(path: Path) -> Tuple[dict, str]:
+    """Parse markdown with optional YAML frontmatter. Returns (meta, body)."""
+    text = Path(path).read_text(encoding="utf-8")
+    match = FRONTMATTER_RE.match(text)
+    if not match:
+        return ({}, text)
+    meta = _yaml_to_dict(match.group(1))
+    return (meta, match.group(2))
+
+
+def write_file(path: Path, meta: dict, body: str) -> None:
+    """Write markdown with frontmatter. Empty meta = body only."""
+    if not meta:
+        Path(path).write_text(body, encoding="utf-8")
+        return
+    yaml_text = _dict_to_yaml(meta)
+    Path(path).write_text(f"---\n{yaml_text}---\n{body}", encoding="utf-8")
+
+
+def _yaml_to_dict(yaml_text: str) -> dict:
+    proc = subprocess.run(
+        ["yq", "-o=json", "."], input=yaml_text,
+        capture_output=True, text=True, check=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def _dict_to_yaml(d: dict) -> str:
+    proc = subprocess.run(
+        ["yq", "-P", "."], input=json.dumps(d),
+        capture_output=True, text=True, check=True,
+    )
+    out = proc.stdout
+    if not out.endswith("\n"):
+        out += "\n"
+    return out

package/skills/work-plan/lib/git_state.py

@@ -0,0 +1,180 @@
+"""Local git queries + time helpers."""
+import subprocess
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+
+def gap_seconds_to_label(seconds: int) -> str:
+    """'Nm ago' / 'Nh ago' / 'Nd ago'."""
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m ago"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h ago"
+    days = hours // 24
+    return f"{days}d ago"
+
+
+def parse_iso_timestamp(s: str) -> datetime:
+    if "T" in s:
+        return datetime.strptime(s, "%Y-%m-%dT%H:%M")
+    return datetime.strptime(s, "%Y-%m-%d")
+
+
+def current_branch(repo_path: Path) -> Optional[str]:
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "branch", "--show-current"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def has_uncommitted(repo_path: Path) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "status", "--short"],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def uncommitted_file_count(repo_path: Path) -> int:
+    if not repo_path or not Path(repo_path).exists():
+        return 0
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "status", "--short"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return 0
+    return len([l for l in proc.stdout.splitlines() if l.strip()])
+
+
+def commits_ahead(branch_name: str, base: str, repo_path: Path) -> int:
+    if not repo_path or not Path(repo_path).exists():
+        return 0
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-list", "--count", f"{base}..{branch_name}"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return 0
+    try:
+        return int(proc.stdout.strip())
+    except ValueError:
+        return 0
+
+
+def branch_exists(branch_name: str, repo_path: Path) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-parse", "--verify", branch_name],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0
+
+
+def _has_recent_commits(branch_name: str, repo_path: Path, hours: int = 24) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    if not branch_exists(branch_name, repo_path):
+        return False
+    since = (datetime.now() - timedelta(hours=hours)).strftime("%Y-%m-%dT%H:%M:%S")
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", branch_name,
+         f"--since={since}", "--pretty=format:%H"],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def branch_in_progress(branch_name: str, repo_path: Path) -> bool:
+    """Detect 'in-progress':
+    - It's the current branch AND has uncommitted changes, OR
+    - It has commits in the last 24 hours.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    if not branch_exists(branch_name, repo_path):
+        return False
+    cur = current_branch(repo_path)
+    if cur == branch_name and has_uncommitted(repo_path):
+        return True
+    return _has_recent_commits(branch_name, repo_path, hours=24)
+
+
+def last_commit_date(branch_name: str, repo_path: Path) -> Optional[datetime]:
+    """Most recent commit timestamp on branch (naive)."""
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    if not branch_exists(branch_name, repo_path):
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", "-1", branch_name, "--pretty=format:%cI"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        s = proc.stdout.strip().split("+")[0].split("Z")[0]
+        return datetime.fromisoformat(s)
+    except (ValueError, IndexError):
+        return None
+
+
+def path_last_commit_date(rel_path: str, repo_path: Path) -> Optional[datetime]:
+    """Timestamp of the most recent commit touching `rel_path` (naive datetime)."""
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", "-1", "--pretty=format:%cI", "--", rel_path],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        s = proc.stdout.strip().split("+")[0].split("Z")[0]
+        return datetime.fromisoformat(s)
+    except (ValueError, IndexError):
+        return None
+
+
+def path_committed_since(rel_path: str, since: date, repo_path: Path) -> bool:
+    """True if `rel_path` has any commit on/around `since` or later (a datetime.date).
+
+    `git log --since` resolves to local midnight and can drop commits made on the
+    plan date itself (timezone-dependent) — the common case where a plan is written
+    and its files land the same day. We widen the window by one day so same-day
+    Modify commits are reliably counted; including the prior day is an acceptable
+    cost for a liveness heuristic.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    window_start = since - timedelta(days=1)
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log",
+         f"--since={window_start.isoformat()}", "--pretty=format:%H", "--", rel_path],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def git_mv(src_rel: str, dst_rel: str, repo_path: Path) -> bool:
+    """git-mv `src_rel` -> `dst_rel` (both repo-relative), creating the dest
+    directory first. Returns True on success. History-preserving."""
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    (Path(repo_path) / dst_rel).parent.mkdir(parents=True, exist_ok=True)
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "mv", src_rel, dst_rel],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0