@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,69 @@
+"""Detect new GitHub issues that should slot into existing tracks."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+from lib.github_state import fetch_recent_issues
+
+
+def build_slug_labels(tracks) -> dict[str, list[str]]:
+    """Build a {slug: [labels]} map from tracks with `github.labels` frontmatter.
+
+    Slugs without an explicit `github.labels` are omitted — callers fall back
+    to the default `track/<slug>` pattern in that case.
+    """
+    out: dict[str, list[str]] = {}
+    for t in tracks:
+        if not getattr(t, "has_frontmatter", False):
+            continue
+        slug = t.meta.get("track", t.name)
+        labels = t.meta.get("github", {}).get("labels")
+        if labels:
+            out[slug] = [str(lab) for lab in labels if str(lab).strip()]
+    return out
+
+
+def match_issue_to_tracks(issue: dict, track_slugs: list[str],
+                          *, slug_labels: dict[str, list[str]] | None = None) -> list[str]:
+    """Return slugs of tracks this issue might belong to.
+
+    1. Configured label match → exact match. Each slug uses its own labels from
+       `slug_labels` if provided, else falls back to `[track/<slug>]`.
+    2. Slug words appear in title → fuzzy match (all >=3-char words must appear).
+    """
+    label_names = {l["name"] for l in issue.get("labels", [])}
+    title_lower = issue.get("title", "").lower()
+    overrides = slug_labels or {}
+
+    matches = set()
+    for slug in track_slugs:
+        labels_for_slug = overrides.get(slug) or [f"track/{slug}"]
+        if any(lab in label_names for lab in labels_for_slug):
+            matches.add(slug)
+
+    for slug in track_slugs:
+        if slug in matches:
+            continue
+        words = [w for w in re.split(r"[-_]", slug) if len(w) >= 3]
+        if not words:
+            continue
+        if all(w.lower() in title_lower for w in words):
+            matches.add(slug)
+
+    return sorted(matches)
+
+
+def find_new_issues_for_tracks(repo: str, track_slugs: list[str],
+                               *, slug_labels: dict[str, list[str]] | None = None,
+                               since_days: int = 7) -> dict[str, list[dict]]:
+    """For each track slug, return list of recent issues that match."""
+    if not track_slugs:
+        return {}
+    since_date = (datetime.now() - timedelta(days=since_days)).strftime("%Y-%m-%d")
+    recent = fetch_recent_issues(repo, since_iso=since_date)
+    out: dict[str, list[dict]] = {s: [] for s in track_slugs}
+    for issue in recent:
+        for slug in match_issue_to_tracks(issue, track_slugs, slug_labels=slug_labels):
+            out[slug].append(issue)
+    return out

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

@@ -0,0 +1,98 @@
+"""Compute a suggested `next_up` issue list for a track.
+
+Sort policy: open issues only, exclude blockers, ranked by priority label
+(P0 < P1 < P2 < P3 with missing label defaulting to P3), then by most-
+recently-updated within the same priority bucket. Closed issues are
+filtered out — `next_up` should never propose work that's already done.
+
+Used by:
+- `commands/handoff.py` — `--auto-next` flag prompts the user to apply
+  the suggestion (with edit/skip options).
+- `commands/brief.py` — when a track sets `next_up_auto: true` in its
+  frontmatter, brief computes the suggestion live at display time and
+  ignores any stored `next_up` list.
+
+The two callers share this helper so the algorithm has one home; if we
+ever want to layer additional signals (assignee, linked PR, milestone),
+they go here.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Iterable
+
+from lib.github_state import extract_priority, short_milestone
+
+PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+DEFAULT_TOP_N = 3
+
+# Milestone alignment ranks: items on the track's declared milestone come
+# first, items on a different milestone next, items with no milestone last.
+MILESTONE_ALIGNED = 0
+MILESTONE_OTHER = 1
+MILESTONE_NONE = 2
+
+
+def _updated_unix(issue: dict) -> float:
+    """Parse the gh-formatted updatedAt field to a unix timestamp.
+
+    Returns 0.0 if the field is missing or unparsable — treats unknown-age
+    issues as oldest, which keeps recently-updated items on top of the
+    suggestion within the same priority bucket.
+    """
+    raw = issue.get("updatedAt") or ""
+    if not raw:
+        return 0.0
+    try:
+        # gh emits 'Z'-suffixed UTC; fromisoformat in 3.9 wants '+00:00'.
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def suggest_next_up(
+    issues: list[dict],
+    blocker_nums: Iterable[int] | None = None,
+    n: int = DEFAULT_TOP_N,
+    track_milestone: str | None = None,
+) -> list[int]:
+    """Return up to `n` issue numbers ranked for "what to work on next."
+
+    Args:
+        issues: issue dicts as returned by `gh issue list --json
+            number,state,labels,milestone,updatedAt,...`.
+        blocker_nums: iterable of issue numbers to exclude (a track's
+            manually-flagged blockers).
+        n: maximum items to return. Default is DEFAULT_TOP_N.
+        track_milestone: optional `milestone_alignment:` value from the
+            track's frontmatter (e.g. `"v0.4.0"`). When provided, issues
+            on this milestone rank above items on any other milestone,
+            which in turn rank above items with no milestone — keeps
+            post-launch deferrals from polluting a launch-window list.
+
+    Returns:
+        List of issue numbers, highest-ranked first. Empty if nothing
+        qualifies (e.g., everything closed or blocked).
+    """
+    blockers = set(blocker_nums or [])
+    candidates = [
+        i for i in issues
+        if str(i.get("state", "")).upper() == "OPEN"
+        and i.get("number") not in blockers
+    ]
+
+    def milestone_rank(issue: dict) -> int:
+        ms = short_milestone(issue.get("milestone"))
+        if not ms:
+            return MILESTONE_NONE
+        if track_milestone and ms == track_milestone:
+            return MILESTONE_ALIGNED
+        return MILESTONE_OTHER
+
+    def sort_key(issue: dict) -> tuple[int, int, float]:
+        pri = extract_priority(issue.get("labels", []))
+        # Negate timestamp so newer comes first within a priority bucket.
+        return (milestone_rank(issue), PRIORITY_RANK.get(pri, 3), -_updated_unix(issue))
+
+    candidates.sort(key=sort_key)
+    return [i["number"] for i in candidates[:n]]

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

@@ -0,0 +1,38 @@
+"""First-creation-only seed for .work-plan/README.md."""
+from pathlib import Path
+
+README_CONTENT = """\
+# .work-plan/
+
+This folder contains **shared planning tracks** managed by [`work-plan`](https://github.com/stylusnexus/work-plan-toolkit).
+
+Each `.md` file is a planning track: a lightweight document with YAML frontmatter that
+points at GitHub issues and captures session notes. GitHub is canonical for issue state;
+these files are the *planning context* that travels with the code.
+
+## Shared vs. private tracks
+
+Tracks in this folder are the **shared tier** — they're committed and sync via `git pull`.
+To keep a track private (personal notes, not for teammates), use `--private` when creating
+it and it will go into your local `notes_root` folder instead.
+
+## Setup
+
+Install the toolkit: [stylusnexus/work-plan-toolkit](https://github.com/stylusnexus/work-plan-toolkit)
+Also available as a Claude/Codex plugin: [stylusnexus/agent-plugins](https://github.com/stylusnexus/agent-plugins)
+"""
+
+
+def seed_readme(work_plan_dir: Path) -> bool:
+    """Write README.md into work_plan_dir if and only if the dir was just created
+    (i.e. it did not previously contain a README.md). Returns True if written.
+
+    Rule: only seeds on first creation. If README.md already exists (even if empty),
+    leaves it alone. If the user deleted it inside an existing folder, does NOT
+    resurrect it — deletion is a respected opt-out.
+    """
+    readme = work_plan_dir / "README.md"
+    if readme.exists():
+        return False
+    readme.write_text(README_CONTENT, encoding="utf-8")
+    return True

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

@@ -0,0 +1,68 @@
+"""Shared CLI helpers: prompts and arg parsing."""
+
+
+def prompt_input(message: str, default: str = "") -> str:
+    """Print prompt and read a free-form line. Treats EOF (no stdin) as default.
+
+    Returns the stripped input, or `default` if EOF or blank.
+    """
+    print(message)
+    try:
+        line = input().strip()
+    except EOFError:
+        return default
+    return line if line else default
+
+
+def prompt_lines() -> list[str]:
+    """Read lines from stdin until blank line or EOF. Returns list of non-blank lines."""
+    out = []
+    try:
+        while True:
+            line = input().rstrip()
+            if not line:
+                break
+            out.append(line)
+    except EOFError:
+        pass
+    return out
+
+
+def prompt_yes_no(message: str = "Apply? [y/N]") -> bool:
+    """Print prompt and read y/N. Treats EOF (no stdin) as no.
+
+    Returns True only if user explicitly types 'y' (case-insensitive).
+    """
+    print(message)
+    try:
+        choice = input().strip().lower()
+    except EOFError:
+        print("(no input — cancelled)")
+        return False
+    return choice == "y"
+
+
+def parse_flags(args: list[str], known: set[str]) -> tuple[dict, list[str]]:
+    """Split CLI args into recognized flags + positional args.
+
+    `known` is the set of flag names this command supports (e.g. {"--all", "--yes"}).
+    For `--key=value` flags, key.split("=", 1)[0] is matched against `known`.
+
+    Returns: (flags_dict, positional_list).
+      - flags_dict: {"--all": True, "--repo": "critforge", ...} for flags found.
+      - positional_list: args that aren't flags.
+
+    Unknown flags are passed through as positional args (caller decides what to do).
+    """
+    flags = {}
+    positional = []
+    for arg in args:
+        if not arg.startswith("--"):
+            positional.append(arg)
+            continue
+        key, _, val = arg.partition("=")
+        if key in known:
+            flags[key] = val if val else True
+        else:
+            positional.append(arg)
+    return flags, positional

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

@@ -0,0 +1,34 @@
+"""Pure helpers for the gated reconcile actions: select actionable rows, compute
+an archive destination, and build the issue title/body for a partial plan.
+"""
+from pathlib import PurePosixPath
+
+
+def dead_rows(rows: list) -> list:
+    return [r for r in rows if r["verdict"] == "dead"]
+
+
+def partial_rows(rows: list) -> list:
+    return [r for r in rows if r["verdict"] == "partial"]
+
+
+def archive_dest(rel: str) -> str:
+    """docs/.../plans/x.md -> docs/.../plans/archive/abandoned/x.md"""
+    p = PurePosixPath(rel)
+    return str(p.parent / "archive" / "abandoned" / p.name)
+
+
+def issue_for(doc, row, unsatisfied) -> tuple:
+    """Build (title, body) for a partial plan's follow-up issue."""
+    stem = PurePosixPath(doc.rel).stem
+    title = f"Finish plan: {stem}"
+    lines = [
+        f"Plan `{doc.rel}` is **partial** "
+        f"({row['files_present']}/{row['files_declared']} declared files present).",
+        "",
+        "Unsatisfied files:",
+    ]
+    for d in unsatisfied:
+        lines.append(f"- [ ] {d.kind}: `{d.path}`")
+    lines += ["", "_Opened by `work-plan plan-status --issues`._"]
+    return title, "\n".join(lines)

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

@@ -0,0 +1,83 @@
+"""Compose terminal output strings."""
+
+
+def time_aware_framing(gap_seconds: int, current_hour: int, handoff_today: bool = True) -> str:
+    """Adapt framing to gap-since-last-activity + hour."""
+    six_hours = 6 * 3600
+    one_hour = 3600
+
+    if gap_seconds > six_hours or current_hour < 11:
+        line = "Fresh start. Here's what changed since you stepped away."
+    elif gap_seconds >= one_hour:
+        line = "Picking back up. Here's what was active when you stepped away."
+    else:
+        line = "Continuing. Drift since last brief:"
+
+    if current_hour >= 23 and not handoff_today:
+        line += "\n  Want a handoff before bed? Run /work-plan handoff [track]."
+
+    return line
+
+
+def render_track_row(t: dict) -> str:
+    """Render one track block in the brief output."""
+    lines = []
+
+    badge_parts = []
+    if t["operational_status"] == "in-progress":
+        badge_parts.append("in-progress")
+    elif t["operational_status"] == "blocked":
+        badge_parts.append("blocked")
+    badge_parts.append(t["launch_priority"])
+    badge_parts.append(t["milestone_alignment"])
+    badge_parts.append(f"last touched {t['last_touched_label']}, last handoff {t['last_handoff_label']}")
+    lines.append(f"▸ {t['name']} ({' · '.join(badge_parts)})")
+
+    if t["next_up"]:
+        for idx, item in enumerate(t["next_up"]):
+            bits = [item["priority"], item["state"]]
+            if item.get("milestone"):
+                bits.append(item["milestone"])
+            label = f"#{item['number']} {item['title']} ({', '.join(bits)})"
+            prefix = "    Up next:    " if idx == 0 else "                "
+            lines.append(prefix + label)
+    elif t.get("next_up_stale_closed_count"):
+        n = t["next_up_stale_closed_count"]
+        slug = t.get("track_slug") or t["name"]
+        plural = "item has" if n == 1 else "items have"
+        lines.append(f"    Up next:    <all {n} {plural} shipped — "
+                     f"run /work-plan handoff {slug} to rotate>")
+    else:
+        lines.append("    Up next:    <empty — set 'next_up:' or all items show backlog>")
+
+    for b in t["active_branches"]:
+        ahead = f"ahead {b['ahead']}" if b["ahead"] else "no commits ahead"
+        uc = f", uncommitted: {b['uncommitted_files']} file(s)" if b["uncommitted_files"] else ""
+        lines.append(f"    Active:     {b['name']} ({ahead}{uc})")
+
+    for n in t["new_issues"]:
+        lines.append(f"    New:        #{n['number']} {n['title']} — slot? [run: /work-plan slot {n['number']}]")
+
+    if t["blockers"]:
+        for b in t["blockers"]:
+            reason = b.get("reason", "manually flagged")
+            lines.append(f"    Blocker:    #{b['number']} — {reason}")
+    else:
+        lines.append("    Blockers:   none")
+
+    if t["drift_items"]:
+        items = ", ".join(f"#{d['issue']}" for d in t["drift_items"])
+        lines.append(f"    Drift:      {items} — body says open but GitHub says closed (or vice versa). "
+                     f"Run /work-plan refresh-md {t['name']}")
+
+    if t["closure_ready"]:
+        lines.append(f"    Closure?:   YES — run /work-plan close {t['name']}")
+    elif t.get("closure_signals_summary"):
+        lines.append(f"    Closure?:   {t['closure_signals_summary']}")
+
+    return "\n".join(lines)
+
+
+def render_archived_reopen(repo: str, slug: str, issue: dict) -> str:
+    return (f"⚠  archive/{slug}.md (shipped) — new issue #{issue['number']} "
+            f"matches this slug. Re-open or slot into a different track?")

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

@@ -0,0 +1,14 @@
+"""Per-user scratch directory for inter-invocation state.
+
+Replaces /tmp/ for the two-step AI subcommands (`group`, `suggest-priorities`)
+so batch + answers files can't be planted by other same-UID processes (#18).
+"""
+from pathlib import Path
+
+
+def cache_dir() -> Path:
+    """Return ~/.claude/work-plan/cache/, created mode 0700 if missing."""
+    p = Path.home() / ".claude" / "work-plan" / "cache"
+    p.mkdir(parents=True, exist_ok=True, mode=0o700)
+    p.chmod(0o700)
+    return p

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

@@ -0,0 +1,39 @@
+"""Append session log entries to track body."""
+
+SESSION_LOG_HEADER = "## Session log"
+
+
+def append_session_log(body: str, timestamp: str,
+                       touched: list[str], next_up: list[str],
+                       blockers: list[dict]) -> str:
+    """Append a `### Session — <timestamp>` block under the Session log section."""
+    block_lines = [f"### Session — {timestamp}\n"]
+    if touched:
+        for t in touched:
+            block_lines.append(f"- Touched: {t}")
+    else:
+        block_lines.append("- Touched: (nothing committed)")
+    if next_up:
+        for n in next_up:
+            block_lines.append(f"- Next: {n}")
+    else:
+        block_lines.append("- Next: (open)")
+    if blockers:
+        for b in blockers:
+            block_lines.append(f"- Blocker: #{b['number']} — {b['reason']}")
+    block_lines.append("")
+    block = "\n".join(block_lines)
+
+    if SESSION_LOG_HEADER in body:
+        idx = body.index(SESSION_LOG_HEADER)
+        rest = body[idx + len(SESSION_LOG_HEADER):]
+        next_h2 = rest.find("\n## ")
+        if next_h2 == -1:
+            insertion = rest + "\n" + block
+        else:
+            insertion = rest[:next_h2] + "\n" + block + rest[next_h2:]
+        return body[:idx] + SESSION_LOG_HEADER + insertion
+
+    if not body.endswith("\n"):
+        body += "\n"
+    return body + f"\n{SESSION_LOG_HEADER}\n\n{block}"

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

@@ -0,0 +1,60 @@
+"""Idempotent status-header stamping for plan/spec docs.
+
+The block is derived ENTIRELY from evidence (no volatile timestamp), so
+re-stamping with unchanged evidence yields a byte-identical document.
+"""
+import re
+
+BEGIN = "<!-- plan-status: BEGIN -->"
+END = "<!-- plan-status: END -->"
+
+_BLOCK_RE = re.compile(re.escape(BEGIN) + r".*?" + re.escape(END), re.DOTALL)
+# Orphan (unpaired) BEGIN/END markers left by a truncated edit or bad merge.
+_ORPHAN_RE = re.compile(
+    r"^[ \t]*(?:" + re.escape(BEGIN) + r"|" + re.escape(END) + r")[ \t]*\n?",
+    re.MULTILINE,
+)
+
+
+def render_block(row: dict) -> str:
+    """Render the delimited status block from an evaluated row dict."""
+    last = row.get("last_touched") or "unknown"
+    line = (
+        f"> **Status:** {row['glyph']} {row['verdict']} · "
+        f"{row['files_present']}/{row['files_declared']} files · "
+        f"last touched {last}"
+    )
+    return f"{BEGIN}\n{line}\n{END}"
+
+
+def stamp(text: str, row: dict) -> str:
+    """Insert or replace the status block. Idempotent for unchanged evidence.
+
+    Hardening: if a doc somehow contains multiple complete blocks, the first is
+    refreshed in place and the rest are removed (no permanently-stale duplicate).
+    If it contains an orphan (unpaired) marker, that is stripped before inserting
+    so a second block can't be stacked on top.
+    """
+    block = render_block(row)
+    if _BLOCK_RE.search(text):
+        # Replace the first block in place (preserving surrounding whitespace),
+        # and drop any additional blocks so none goes stale.
+        seen = {"first": False}
+
+        def _sub(_m):
+            if not seen["first"]:
+                seen["first"] = True
+                return block
+            return ""
+
+        return _BLOCK_RE.sub(_sub, text)
+
+    # No complete block. Clear any orphan markers (corrupted/dangling) so we
+    # don't stack a duplicate block on top. No-op on well-formed docs.
+    text = _ORPHAN_RE.sub("", text)
+    lines = text.splitlines(keepends=True)
+    for i, ln in enumerate(lines):
+        if ln.startswith("# "):
+            lines.insert(i + 1, "\n" + block + "\n")
+            return "".join(lines)
+    return block + "\n\n" + text