@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,247 @@
+"""brief subcommand — fully featured."""
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, discover_archived_tracks, filter_tracks_by_repo
+from lib.github_state import fetch_issues, extract_priority, short_milestone
+from lib.prompts import parse_flags
+from lib.git_state import (
+    parse_iso_timestamp, gap_seconds_to_label,
+    branch_in_progress, commits_ahead, uncommitted_file_count, current_branch,
+)
+from lib.closure import compute_signals, is_closure_ready
+from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
+from lib.next_up import suggest_next_up
+from lib.drift import detect_drift
+from lib.render import time_aware_framing, render_track_row, render_archived_reopen
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--repo"})
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py brief [--repo=<key>]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", flush=True)
+        return 1
+
+    tracks = discover_tracks(cfg)
+    if repo_key:
+        scoped = filter_tracks_by_repo(tracks, repo_key)
+        if not scoped:
+            print(f"No tracks found for repo '{repo_key}'.")
+            available = sorted((cfg.get("repos") or {}).keys())
+            if available:
+                print(f"Configured repo keys: {', '.join(available)}")
+            return 0
+        tracks = scoped
+    active = [t for t in tracks if t.has_frontmatter
+              and t.meta.get("status") in ("active", "in-progress", "blocked")]
+
+    if not active and not tracks:
+        print("No tracks found.")
+        return 0
+
+    now = datetime.now()
+    most_recent = max(
+        (parse_iso_timestamp(t.meta["last_touched"]) for t in active if t.meta.get("last_touched")),
+        default=None,
+    )
+    gap = int((now - most_recent).total_seconds()) if most_recent else 999999
+    handoff_today = any(
+        t.meta.get("last_handoff", "").startswith(now.strftime("%Y-%m-%d")) for t in active
+    )
+    framing = time_aware_framing(gap, now.hour, handoff_today)
+
+    print(f"DAILY BRIEF — {now.strftime('%Y-%m-%d %H:%M')} (gap: {gap_seconds_to_label(gap)})")
+    print()
+    print(framing)
+    print()
+
+    blocks = []
+    for t in active:
+        b = _build_track_block(t, cfg, now)
+        blocks.append((b["sort_key"], b))
+
+    blocks.sort(key=lambda x: x[0])
+    for _, block in blocks:
+        print(render_track_row(block))
+        print()
+
+    needs_init = [t for t in tracks if t.needs_init]
+    needs_filing = [t for t in tracks if t.needs_filing]
+    if needs_init or needs_filing:
+        print("--- Setup needed ---")
+        for t in needs_init:
+            print(f"  needs init:   {t.path}  → /work-plan init '{t.path}'")
+        for t in needs_filing:
+            print(f"  needs filing: {t.path}  → move into a repo subfolder")
+        print()
+
+    _surface_archived_reopens(cfg, repo_key=repo_key)
+
+    n_active = len(active)
+    n_in_progress = sum(1 for _, b in blocks if b["operational_status"] == "in-progress")
+    n_closure = sum(1 for _, b in blocks if b["closure_ready"])
+    n_drift = sum(1 for _, b in blocks if b["drift_items"])
+    n_new = sum(len(b["new_issues"]) for _, b in blocks)
+    print(f"{n_active} active tracks. "
+          f"{n_in_progress} in-progress. {n_closure} closure-ready. "
+          f"{n_drift} with drift. {n_new} new issues to slot.")
+
+    return 0
+
+
+def _build_track_block(track, cfg, now: datetime) -> dict:
+    meta = track.meta
+    repo = track.repo
+    local = track.local_path
+
+    issue_nums = meta.get("github", {}).get("issues") or []
+    stored_next_up = meta.get("next_up") or []
+    # Fetch state for stored next_up issues even if they're not in github.issues,
+    # so stale closed entries surface as a clear signal rather than vanishing.
+    fetch_nums = sorted(set(issue_nums) | set(stored_next_up))
+    issues = fetch_issues(repo, fetch_nums) if (repo and fetch_nums) else []
+    issues_by_num = {i["number"]: i for i in issues}
+
+    # When `next_up_auto: true` is set in track frontmatter, derive the list
+    # live from open issues (priority-sorted, blockers excluded) instead of
+    # reading the stored `next_up`. The track's persisted list is ignored
+    # for display purposes — useful for tracks where you don't want to
+    # hand-curate but still want a sensible "what's next" surfaced.
+    track_milestone = meta.get("milestone_alignment") or None
+    if meta.get("next_up_auto") and issues:
+        blocker_nums = meta.get("blockers") or []
+        next_up_nums = suggest_next_up(issues, blocker_nums, track_milestone=track_milestone)
+    else:
+        next_up_nums = stored_next_up
+
+    next_up_items = []
+    next_up_closed_count = 0
+    for num in next_up_nums:
+        i = issues_by_num.get(num)
+        if not i:
+            continue
+        state = (i.get("state") or "").upper()
+        if state in ("CLOSED", "MERGED"):
+            next_up_closed_count += 1
+            continue
+        next_up_items.append({
+            "number": num, "title": i.get("title", ""),
+            "priority": extract_priority(i.get("labels", [])),
+            "state": state.lower() or "open",
+            "milestone": short_milestone(i.get("milestone")),
+        })
+
+    branch_names = meta.get("github", {}).get("branches") or []
+    active_branches = []
+    branch_in_prog = False
+    for bn in branch_names:
+        in_prog = branch_in_progress(bn, local)
+        if in_prog:
+            branch_in_prog = True
+        active_branches.append({
+            "name": bn,
+            "ahead": commits_ahead(bn, "dev", local) if local else 0,
+            "uncommitted_files": (
+                uncommitted_file_count(local)
+                if local and current_branch(local) == bn else 0
+            ),
+        })
+
+    stored_status = meta.get("status", "active")
+    if stored_status == "active" and branch_in_prog:
+        operational_status = "in-progress"
+    else:
+        operational_status = stored_status
+
+    track_slug = meta.get("track", track.name)
+    slug_labels = build_slug_labels([track])
+    new_issues_map = find_new_issues_for_tracks(repo, [track_slug], slug_labels=slug_labels, since_days=7) if repo else {}
+    listed_set = set(issue_nums)
+    new_issues = []
+    for issue in new_issues_map.get(track_slug, []):
+        if issue["number"] in listed_set:
+            continue
+        new_issues.append({"number": issue["number"], "title": issue["title"]})
+
+    drift_items = detect_drift(track.body, issues) if issues else []
+
+    related_recent_count = len(new_issues_map.get(track_slug, []))
+    signals = compute_signals(meta, issues, local, related_recent_count)
+    closure_ready, _ = is_closure_ready(signals)
+    if closure_ready:
+        closure_signals_summary = None
+    else:
+        green = sum([signals.all_issues_closed, signals.all_branches_done,
+                     signals.next_up_empty, signals.cold_14d, signals.no_recent_related_issues])
+        closure_signals_summary = f"{green}/5 signals green"
+
+    blockers = [{"number": bn, "reason": "manually flagged"}
+                for bn in (meta.get("blockers") or [])]
+
+    def lbl(key):
+        if not meta.get(key):
+            return "?"
+        gs = (now - parse_iso_timestamp(meta[key])).total_seconds()
+        return gap_seconds_to_label(int(gs))
+
+    in_prog_rank = 0 if operational_status == "in-progress" else 1
+    pri_rank = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}.get(meta.get("launch_priority", "P3"), 3)
+    recency_key = (
+        -parse_iso_timestamp(meta["last_touched"]).timestamp()
+        if meta.get("last_touched") else 0
+    )
+
+    return {
+        "name": meta.get("track", track.name),
+        "operational_status": operational_status,
+        "launch_priority": meta.get("launch_priority", "P3"),
+        "milestone_alignment": meta.get("milestone_alignment", "—"),
+        "last_touched_label": lbl("last_touched"),
+        "last_handoff_label": lbl("last_handoff"),
+        "next_up": next_up_items,
+        "next_up_stale_closed_count": (
+            next_up_closed_count if not next_up_items and next_up_nums else 0
+        ),
+        "track_slug": meta.get("track", track.name),
+        "active_branches": active_branches,
+        "new_issues": new_issues,
+        "blockers": blockers,
+        "drift_items": drift_items,
+        "closure_ready": closure_ready,
+        "closure_signals_summary": closure_signals_summary,
+        "archived_reopen": [],
+        "sort_key": (in_prog_rank, pri_rank, recency_key),
+    }
+
+
+def _surface_archived_reopens(cfg: dict, repo_key: str = None) -> None:
+    archived = discover_archived_tracks(cfg)
+    if repo_key:
+        archived = filter_tracks_by_repo(archived, repo_key)
+    if not archived:
+        return
+    by_repo: dict[str, list] = {}
+    for a in archived:
+        if a.repo:
+            by_repo.setdefault(a.repo, []).append(a)
+    callouts = []
+    for repo, tracks_in_repo in by_repo.items():
+        slugs = [a.meta.get("track", a.name) for a in tracks_in_repo]
+        slug_labels = build_slug_labels(tracks_in_repo)
+        new_map = find_new_issues_for_tracks(repo, slugs, slug_labels=slug_labels, since_days=14)
+        for slug, issues in new_map.items():
+            for issue in issues:
+                callouts.append((slug, issue))
+    if callouts:
+        print("--- Archived tracks with new activity ---")
+        for slug, issue in callouts:
+            print("  " + render_archived_reopen(repo, slug, issue))
+        print()

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

@@ -0,0 +1,139 @@
+"""canonicalize subcommand: add a canonical master issue table to a track.
+
+Generates one-row-per-issue table from frontmatter github.issues, with assignee
+and status columns. Inserts at top of body with a marker so refresh-md targets
+ONLY this table (skipping narrative tables in the existing body).
+
+Use --all to canonicalize every active track that doesn't yet have one.
+"""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
+from lib.github_state import fetch_issues, state_to_status_label, format_assignees
+from lib.frontmatter import write_file
+from lib.status_table import CANONICAL_MARKER, find_canonical_status_tables, render_issue_row
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--all", "--force", "--repo"})
+    do_all = flags.get("--all", False)
+    force = flags.get("--force", False)
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    track_arg = positional[0] if positional else None
+
+    if not do_all and not track_arg:
+        print("usage: work_plan.py canonicalize <track-name> | --all  [--force] [--repo=<key>]")
+        return 2
+
+    track_name = track_arg
+    repo_qualifier = repo_flag
+    if track_arg:
+        name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+        track_name = name_from_arg
+        if repo_from_arg:
+            repo_qualifier = repo_from_arg
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    if do_all:
+        targets = [t for t in tracks if t.has_frontmatter
+                   and t.meta.get("status") in ("active", "in-progress", "blocked")]
+        if repo_qualifier:
+            from lib.tracks import filter_tracks_by_repo
+            targets = filter_tracks_by_repo(targets, repo_qualifier)
+    else:
+        try:
+            target = find_track_by_name(track_name, tracks, active_only=True,
+                                        repo=repo_qualifier)
+        except AmbiguousTrackError as e:
+            print(str(e))
+            return 1
+        if not target:
+            print(f"No active track matching '{track_name}'.")
+            return 1
+        targets = [target]
+
+    any_changes = False
+    for track in targets:
+        existing = find_canonical_status_tables(track.body)
+        if existing and not force:
+            print(f"  skip {track.name}: already has canonical table (use --force to replace)")
+            continue
+
+        issue_nums = track.meta.get("github", {}).get("issues") or []
+        if not issue_nums or not track.repo:
+            print(f"  skip {track.name}: no issues or repo")
+            continue
+
+        print(f"  fetching {len(issue_nums)} issue(s) for {track.name}...")
+        issues = fetch_issues(track.repo, issue_nums)
+        issues_by_num = {i["number"]: i for i in issues}
+
+        new_body = _insert_canonical_table(
+            track.body, issue_nums, issues_by_num, replace=force,
+        )
+        write_file(track.path, track.meta, new_body)
+        print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
+        any_changes = True
+
+    if not any_changes:
+        print("Nothing to do.")
+    return 0
+
+
+def _insert_canonical_table(body: str, issue_nums: list[int],
+                            issues_by_num: dict, replace: bool = False) -> str:
+    """Insert (or replace) a canonical table at the top of the body."""
+    table_md = _render_canonical_table(issue_nums, issues_by_num)
+
+    if replace:
+        # Strip existing canonical block (marker + heading + table + separator)
+        body = _strip_existing_canonical(body)
+
+    # Prepend table after any leading whitespace
+    body_stripped = body.lstrip("\n")
+    leading_whitespace = body[: len(body) - len(body_stripped)]
+    return leading_whitespace + table_md + "\n---\n\n" + body_stripped
+
+
+def _render_canonical_table(issue_nums: list[int], issues_by_num: dict) -> str:
+    lines = [
+        "## Issues (canonical)",
+        "",
+        f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
+        "",
+        "| # | Title | Assignee | Status |",
+        "|---|---|---|---|",
+    ]
+    for num in sorted(issue_nums):
+        i = issues_by_num.get(num, {})
+        lines.append(render_issue_row(
+            num, i.get("title", "(not fetched)"),
+            format_assignees(i), state_to_status_label(i.get("state")),
+        ))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _strip_existing_canonical(body: str) -> str:
+    """Remove an existing canonical-table block from the top of the body."""
+    if CANONICAL_MARKER not in body:
+        return body
+    # Find the start of the heading "## Issues (canonical)" if present, else the marker
+    heading_idx = body.find("## Issues (canonical)")
+    marker_idx = body.find(CANONICAL_MARKER)
+    start = heading_idx if 0 <= heading_idx < marker_idx else marker_idx
+    # Find end: the next "---\n" separator after the marker
+    sep_idx = body.find("\n---\n", marker_idx)
+    if sep_idx == -1:
+        # No separator — strip just the marker line
+        end = body.find("\n", marker_idx) + 1
+    else:
+        end = sep_idx + len("\n---\n")
+    return body[:start] + body[end:].lstrip("\n")

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

@@ -0,0 +1,98 @@
+"""close subcommand — non-interactive, flag-driven."""
+import json
+import shutil
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+VALID_STATES = {"shipped", "parked", "abandoned"}
+
+
+def run(args: list[str]) -> int:
+    # --confirm uses equals form: --confirm=<token>
+    # --state and --note also use equals form: --state=shipped, --note=...
+    # --repo uses equals form: --repo=<key>
+    flags, positional = parse_flags(args, {"--state", "--note", "--confirm", "--repo"})
+
+    if not positional:
+        print("usage: work_plan.py close <track-name> --state=shipped|parked|abandoned [--note=<text>] [--confirm=<token>] [--repo=<key>]")
+        return 2
+
+    track_arg = positional[0]
+    name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+    track_name = name_from_arg
+    repo_qualifier = repo_from_arg or (flags.get("--repo") if flags.get("--repo") is not True else None)
+
+    # Validate --state (required)
+    end_state = flags.get("--state")
+    if not end_state or end_state not in VALID_STATES:
+        if not end_state:
+            print("ERROR: --state is required (shipped|parked|abandoned).")
+        else:
+            print(f"ERROR: --state={end_state!r} is not valid (allowed: abandoned, parked, shipped).")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    try:
+        track = find_track_by_name(track_name, tracks, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+    if not track:
+        print(f"No track matching '{track_name}'.")
+        return 1
+
+    # Public-repo confirm gate (the extension surfaces this as a modal).
+    # Placed after track resolution but before any write/move.
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{track.repo} is PUBLIC (or visibility unknown); "
+                f"closing '{track.name}' will be written there."
+            ),
+            "token": make_token(track.repo, track.name),
+        }))
+        return 0
+
+    # Apply state and optional wrap-up note.
+    track.meta["status"] = end_state
+    new_body = track.body
+    note = flags.get("--note")
+    if note and isinstance(note, str) and note.strip():
+        new_body += f"\n\n## Wrap-up\n\n{note}\n"
+
+    write_file(track.path, track.meta, new_body)
+
+    if end_state == "parked":
+        print(f"✓ '{track.name}' marked parked. Stays in place.")
+        return 0
+
+    notes_root = Path(cfg["notes_root"])
+    folder = track.path.parent
+    archive_dir = folder / "archive" / end_state
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    dest = archive_dir / track.path.name
+    shutil.move(str(track.path), str(dest))
+    # Use relative path from tier root; fall back to absolute if outside notes_root
+    try:
+        display = dest.relative_to(notes_root)
+    except ValueError:
+        display = dest
+    print(f"✓ '{track.name}' marked {end_state}, moved to {display}")
+    if getattr(track, "tier", None) == "shared":
+        print("  ↑ shared track — commit + push to share this archive with teammates.")
+    return 0

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

@@ -0,0 +1,100 @@
+"""coverage subcommand: report open issues not referenced by any track.
+
+Read-only. Fetches live from gh — no cache. Use --repo=<key> to scope to
+one repo; omit for all configured repos. Use --list to print untracked
+issue titles. Use --limit=N to control how many are shown (default 20).
+"""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks
+from lib.github_state import fetch_open_issues
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--list", "--repo"})
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+    show_list = bool(flags.get("--list"))
+
+    limit = 20
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    repos_cfg = cfg.get("repos", {})
+
+    if repo_flag:
+        if repo_flag not in repos_cfg:
+            print(f"ERROR: repo folder '{repo_flag}' not in config.yml.")
+            return 1
+        folders = [repo_flag]
+    else:
+        folders = list(repos_cfg.keys())
+
+    if not folders:
+        print("ERROR: no repos configured in config.yml.")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    # Build per-repo set of tracked issue numbers across all tracks.
+    tracked_by_repo: dict[str, set] = {}
+    for t in tracks:
+        if not t.repo or not t.has_frontmatter:
+            continue
+        nums = t.meta.get("github", {}).get("issues") or []
+        tracked_by_repo.setdefault(t.repo, set()).update(nums)
+
+    any_output = False
+    for folder in folders:
+        repo = repos_cfg[folder].get("github")
+        if not repo:
+            continue
+
+        print(f"Fetching open issues for {repo}...")
+        open_issues = fetch_open_issues(repo)
+        tracked = tracked_by_repo.get(repo, set())
+
+        untracked = [i for i in open_issues if i.get("number") not in tracked]
+        total = len(open_issues)
+        n_untracked = len(untracked)
+        n_tracked = total - n_untracked
+        pct_tracked = round(100 * n_tracked / total) if total else 0
+        pct_untracked = 100 - pct_tracked if total else 0
+
+        print()
+        print(f"{folder} ({repo}):")
+        print(f"  Open issues:  {total}")
+        if total == 0:
+            print("  No open issues.")
+        else:
+            print(f"  In a track:   {n_tracked}  ({pct_tracked}%)")
+            if n_untracked == 0:
+                print("  Untracked:    0  — full coverage!")
+            else:
+                print(f"  Untracked:    {n_untracked}  ({pct_untracked}%)")
+                if show_list:
+                    shown = untracked[:limit]
+                    for i in shown:
+                        num = i.get("number", "?")
+                        title = i.get("title", "")
+                        print(f"    #{num} {title}")
+                    remainder = n_untracked - len(shown)
+                    if remainder > 0:
+                        print(f"    … and {remainder} more")
+                else:
+                    print(f"  Run with --list to see titles, or /work-plan group to cluster.")
+        any_output = True
+
+    if not any_output:
+        print("No repos with a 'github' entry found in config.")
+    return 0