@stylusnexus/work-plan 2026.6.9 → 2026.6.10

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

@@ -0,0 +1,184 @@
+"""batch-slot subcommand — slot multiple issues into a track at once."""
+import json
+import subprocess
+
+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
+
+
+def _find_prior_owners(issue_num: int, repo: str, target_name: str, tracks):
+    """Active tracks in `repo` (excluding `target_name`) whose frontmatter
+    already lists `issue_num`. Shared with slot.py."""
+    owners = []
+    for t in tracks:
+        if not t.has_frontmatter or t.name == target_name or t.repo != repo:
+            continue
+        if t.meta.get("status") not in ("active", "in-progress", "blocked"):
+            continue
+        if issue_num in (t.meta.get("github", {}).get("issues") or []):
+            owners.append(t)
+    return owners
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--confirm", "--move", "--no-move", "--repo"}
+    )
+
+    if len(positional) < 2:
+        print(
+            "usage: work_plan.py batch-slot <issue-num>... <track | track@repo>"
+            " [--repo=<key>]"
+        )
+        return 2
+
+    # Last positional is the track; everything before is an issue number.
+    *issue_strs, target_arg = positional
+
+    issue_nums: list[int] = []
+    for s in issue_strs:
+        try:
+            issue_nums.append(int(s))
+        except ValueError:
+            print(f"ERROR: '{s}' is not an issue number.")
+            return 2
+
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    target_name = target_arg
+    repo_qualifier = repo_flag
+    if target_arg:
+        name_from_arg, repo_from_arg = parse_track_repo_arg(target_arg)
+        target_name = name_from_arg
+        if repo_from_arg:
+            repo_qualifier = repo_from_arg
+
+    if "--move" in flags and "--no-move" in flags:
+        print("ERROR: --move and --no-move are mutually exclusive.")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    try:
+        target = find_track_by_name(
+            target_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 '{target_name}'.")
+        return 1
+
+    # Confirm gate — fire once for the whole batch.
+    confirm = flags.get("--confirm")
+    if target.repo and needs_confirm(target.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, target.repo, target.name)
+    ):
+        print(
+            json.dumps(
+                {
+                    "needs_confirm": True,
+                    "reason": (
+                        f"{target.repo} is PUBLIC (or visibility unknown); "
+                        f"batch-slotting {len(issue_nums)} issue(s) will be"
+                        f" written there."
+                    ),
+                    "token": make_token(target.repo, target.name),
+                }
+            )
+        )
+        return 0
+
+    do_move = "--move" in flags
+
+    # Collect source tracks that need issue removal (consolidated per source).
+    source_removals: dict[str, tuple] = {}  # source_name -> (source_track, set[issue_num])
+
+    issues = list(target.meta.get("github", {}).get("issues") or [])
+    skipped: list[int] = []
+    slotted: list[int] = []
+
+    for issue_num in issue_nums:
+        if issue_num in issues:
+            skipped.append(issue_num)
+            continue
+
+        # Milestone mismatch check (non-blocking warning).
+        proc = subprocess.run(
+            ["gh", "issue", "view", str(issue_num),
+             "--repo", target.repo, "--json", "milestone"],
+            capture_output=True, text=True,
+        )
+        if proc.returncode == 0:
+            info = json.loads(proc.stdout)
+            m = info.get("milestone", {})
+            if (
+                m and m.get("title")
+                and m["title"] != target.meta.get("milestone_alignment")
+            ):
+                print(
+                    f"⚠  #{issue_num} is on milestone '{m['title']}', "
+                    f"track '{target.name}' aligned to"
+                    f" '{target.meta.get('milestone_alignment')}'."
+                )
+
+        # Prior-owner detection.
+        sources = _find_prior_owners(
+            issue_num, target.repo, target.name, tracks
+        )
+
+        issues.append(issue_num)
+        slotted.append(issue_num)
+
+        if sources and do_move:
+            for src in sources:
+                if src.name not in source_removals:
+                    source_removals[src.name] = (src, set())
+                source_removals[src.name][1].add(issue_num)
+        elif sources and not do_move:
+            names = ", ".join(f"'{t.name}'" for t in sources)
+            print(
+                f"ℹ #{issue_num} still listed in {names}"
+                f" — re-run with --move to relocate."
+            )
+
+    if not slotted:
+        if skipped:
+            print(
+                f"All {len(skipped)} issue(s) already in track"
+                f" '{target.name}'."
+            )
+        return 0
+
+    # Write source tracks (consolidated removals).
+    if do_move:
+        for src_name, (src, removals) in source_removals.items():
+            src_issues = [
+                n for n in (src.meta.get("github", {}).get("issues") or [])
+                if n not in removals
+            ]
+            src.meta.setdefault("github", {})["issues"] = src_issues
+            write_file(src.path, src.meta, src.body)
+            removed_str = ", ".join(f"#{n}" for n in sorted(removals))
+            print(f"  ✓ Removed {removed_str} from '{src_name}'.")
+
+    # Write target track once.
+    target.meta.setdefault("github", {})["issues"] = sorted(issues)
+    write_file(target.path, target.meta, target.body)
+
+    slotted_str = ", ".join(f"#{n}" for n in slotted)
+    print(f"✓ Slotted {slotted_str} into '{target.name}'.")
+    if skipped:
+        skipped_str = ", ".join(f"#{n}" for n in skipped)
+        print(f"ℹ Skipped (already in track): {skipped_str}.")
+    return 0

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

@@ -3,7 +3,10 @@ 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.tracks import (
+    discover_tracks, discover_archived_tracks, filter_tracks_by_repo,
+    priority_rank, recency_sort_key,
+)
 from lib.github_state import fetch_issues, extract_priority, short_milestone
 from lib.prompts import parse_flags
 from lib.git_state import (
@@ -193,11 +196,8 @@ def _build_track_block(track, cfg, now: datetime) -> dict:
         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
-    )
+    pri_rank = priority_rank(meta)
+    recency_key = recency_sort_key(meta)
 
     return {
         "name": meta.get("track", track.name),

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

@@ -7,7 +7,7 @@ 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
+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
@@ -15,15 +15,24 @@ from lib.prompts import parse_flags
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--all", "--force"})
+    flags, positional = parse_flags(args, {"--all", "--force", "--repo"})
     do_all = flags.get("--all", False)
     force = flags.get("--force", False)
-    track_name = positional[0] if positional else None
+    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_name:
-        print("usage: work_plan.py canonicalize <track-name> | --all  [--force]")
+    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:
@@ -35,8 +44,16 @@ def run(args: list[str]) -> int:
     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:
-        target = find_track_by_name(track_name, tracks, active_only=True)
+        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
@@ -60,6 +77,7 @@ def run(args: list[str]) -> int:
 
         new_body = _insert_canonical_table(
             track.body, issue_nums, issues_by_num, replace=force,
+            milestone_alignment=track.meta.get("milestone_alignment"),
         )
         write_file(track.path, track.meta, new_body)
         print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
@@ -71,9 +89,10 @@ def run(args: list[str]) -> int:
 
 
 def _insert_canonical_table(body: str, issue_nums: list[int],
-                            issues_by_num: dict, replace: bool = False) -> str:
+                            issues_by_num: dict, replace: bool = False,
+                            milestone_alignment=None) -> str:
     """Insert (or replace) a canonical table at the top of the body."""
-    table_md = _render_canonical_table(issue_nums, issues_by_num)
+    table_md = _render_canonical_table(issue_nums, issues_by_num, milestone_alignment)
 
     if replace:
         # Strip existing canonical block (marker + heading + table + separator)
@@ -85,22 +104,57 @@ def _insert_canonical_table(body: str, issue_nums: list[int],
     return leading_whitespace + table_md + "\n---\n\n" + body_stripped
 
 
-def _render_canonical_table(issue_nums: list[int], issues_by_num: dict) -> str:
+def _render_canonical_table(issue_nums: list[int], issues_by_num: dict,
+                            milestone_alignment=None) -> str:
     lines = [
         "## Issues (canonical)",
         "",
         f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
         "",
-        "| # | Title | Assignee | Status |",
-        "|---|---|---|---|",
     ]
+
+    # Build a normalized issue list with compact milestone strings.
+    from lib.github_state import short_milestone
+    norm_issues = []
     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("")
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm_issues.append({"number": num, "milestone": ms, "_gh": gh})
+
+    from lib.export_model import group_issues_by_milestone
+    groups = group_issues_by_milestone(norm_issues, milestone_alignment)
+
+    if len(groups) <= 1:
+        # Single milestone group (or all null) — render flat, same as before.
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        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)
+
+    # Multiple milestone groups — render with section headings.
+    for label, issues in groups:
+        if label:
+            heading = f"{label} ({len(issues)})"
+        else:
+            heading = f"No milestone ({len(issues)})"
+        lines.append(f"### {heading}")
+        lines.append("")
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        for norm in issues:
+            num = norm["number"]
+            i = norm["_gh"]
+            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)
 
 

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

@@ -4,7 +4,7 @@ import shutil
 from pathlib import Path
 
 from lib.config import load_config, ConfigError
-from lib.tracks import discover_tracks, find_track_by_name
+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
@@ -15,13 +15,17 @@ 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=...
-    flags, positional = parse_flags(args, {"--state", "--note", "--confirm"})
+    # --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>]")
+        print("usage: work_plan.py close <track-name> --state=shipped|parked|abandoned [--note=<text>] [--confirm=<token>] [--repo=<key>]")
         return 2
 
-    track_name = positional[0]
+    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")
@@ -39,7 +43,11 @@ def run(args: list[str]) -> int:
         return 1
 
     tracks = discover_tracks(cfg)
-    track = find_track_by_name(track_name, tracks)
+    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
@@ -79,5 +87,12 @@ def run(args: list[str]) -> int:
     archive_dir.mkdir(parents=True, exist_ok=True)
     dest = archive_dir / track.path.name
     shutil.move(str(track.path), str(dest))
-    print(f"✓ '{track.name}' marked {end_state}, moved to {dest.relative_to(notes_root)}")
+    # 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

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

@@ -23,10 +23,12 @@ def run(args: list[str]) -> int:
     threshold_arg = next((a for a in args if a.startswith("--min-similarity=")), None)
     limit_arg = next((a for a in args if a.startswith("--limit=")), None)
     state_arg = next((a for a in args if a.startswith("--state=")), None)
+    timeout_arg = next((a for a in args if a.startswith("--timeout=")), None)
 
     threshold = float(threshold_arg.split("=", 1)[1]) if threshold_arg else 0.70
     limit = int(limit_arg.split("=", 1)[1]) if limit_arg else 20
     state = state_arg.split("=", 1)[1] if state_arg else "open"
+    gh_timeout = int(timeout_arg.split("=", 1)[1]) if timeout_arg else 30
 
     try:
         cfg = load_config()
@@ -49,12 +51,17 @@ def run(args: list[str]) -> int:
     repo = cfg["repos"][folder]["github"]
 
     print(f"Fetching {state} issues from {repo}...")
-    proc = subprocess.run(
-        ["gh", "issue", "list", "--repo", repo,
-         "--state", state, "--limit", "1000",
-         "--json", "number,title,url"],
-        capture_output=True, text=True,
-    )
+    try:
+        proc = subprocess.run(
+            ["gh", "issue", "list", "--repo", repo,
+             "--state", state, "--limit", "1000",
+             "--json", "number,title,url"],
+            capture_output=True, text=True,
+            timeout=gh_timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(f"ERROR: gh issue list timed out after {gh_timeout}s")
+        return 1
     if proc.returncode != 0:
         print(f"ERROR fetching issues: {proc.stderr}")
         return 1
@@ -69,11 +76,15 @@ def run(args: list[str]) -> int:
 
     # Pairwise similarity (O(n²) but fine for n<=1000)
     pairs = []
-    for idx_a in range(len(normalized)):
+    total = len(normalized)
+    tick_interval = max(1, total // 10)
+    for idx_a in range(total):
+        if idx_a % tick_interval == 0:
+            print(f"  ... {idx_a}/{total} compared", end="\r", flush=True)
         a, norm_a = normalized[idx_a]
         if len(norm_a) < 5:
             continue
-        for idx_b in range(idx_a + 1, len(normalized)):
+        for idx_b in range(idx_a + 1, total):
             b, norm_b = normalized[idx_b]
             if len(norm_b) < 5:
                 continue
@@ -81,6 +92,8 @@ def run(args: list[str]) -> int:
             if ratio >= threshold:
                 pairs.append((ratio, a, b))
 
+    print()  # clear the \r progress line
+
     pairs.sort(key=lambda x: -x[0])
     pairs = pairs[:limit]