@stylusnexus/work-plan 2026.6.9

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

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

@@ -0,0 +1,227 @@
+"""Find + update first markdown table with a Status column."""
+import re
+from typing import Optional
+
+ISSUE_NUM_RE = re.compile(r"#(\d+)")
+CANONICAL_MARKER = "<!-- canonical-issue-table"
+
+
+def find_status_table(body: str) -> Optional[dict]:
+    """Find the first markdown table with a 'Status' column AND issue refs.
+
+    Prefers tables whose data rows contain `#NNNN` references over tables that
+    happen to have a 'Status' column for non-issue purposes. Falls back to the
+    first 'Status' table if none have issue refs.
+    """
+    tables = find_all_status_tables(body, with_issue_refs_only=False)
+    with_refs = [t for t in tables if t["has_issue_refs"]]
+    if with_refs:
+        return with_refs[0]
+    return tables[0] if tables else None
+
+
+def find_all_status_tables(body: str, with_issue_refs_only: bool = True) -> list[dict]:
+    """Find every markdown table with a 'Status' column.
+
+    Returns a list of table dicts, each with: header_line_idx, rows,
+    status_col_index, has_issue_refs, is_canonical.
+
+    `is_canonical` is True if the table is preceded (within 3 lines) by a
+    `<!-- canonical-issue-table -->` comment. Refresh-md prefers canonical
+    tables when present.
+
+    If with_issue_refs_only=True (default), only returns tables whose data rows
+    contain `#NNNN` references.
+    """
+    lines = body.split("\n")
+    tables = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if "|" not in line:
+            i += 1
+            continue
+        cells = _parse_row(line)
+        if not cells:
+            i += 1
+            continue
+        status_idx = next((idx for idx, c in enumerate(cells) if c.strip().lower() == "status"), None)
+        if status_idx is None:
+            i += 1
+            continue
+        if i + 1 >= len(lines) or not _is_separator(lines[i + 1]):
+            i += 1
+            continue
+        # Look backward up to 3 lines for canonical marker
+        is_canonical = any(
+            CANONICAL_MARKER in lines[k]
+            for k in range(max(0, i - 3), i)
+        )
+        rows = []
+        j = i + 2
+        while j < len(lines):
+            if "|" not in lines[j]:
+                break
+            row_cells = _parse_row(lines[j])
+            if not row_cells:
+                break
+            rows.append({"raw": lines[j], "cells": row_cells, "line_idx": j})
+            j += 1
+        has_refs = any(ISSUE_NUM_RE.search(cell) for row in rows for cell in row["cells"])
+        if not with_issue_refs_only or has_refs:
+            tables.append({
+                "header_line_idx": i,
+                "rows": rows,
+                "status_col_index": status_idx,
+                "has_issue_refs": has_refs,
+                "is_canonical": is_canonical,
+            })
+        i = j
+    return tables
+
+
+def find_canonical_status_tables(body: str) -> list[dict]:
+    """Return only canonical-marked status tables."""
+    return [t for t in find_all_status_tables(body) if t["is_canonical"]]
+
+
+def update_row_status(body: str, issue_num: int, new_status: str) -> str:
+    table = find_status_table(body)
+    if not table:
+        return body
+    lines = body.split("\n")
+    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 issue_num not in nums:
+            continue
+        new_cells = list(row["cells"])
+        new_cells[sidx] = " " + new_status + " "
+        lines[row["line_idx"]] = "|" + "|".join(new_cells) + "|"
+        break
+    return "\n".join(lines)
+
+
+def render_issue_row(num: int, title: str, assignee: str, status: str) -> str:
+    """Render a canonical issue-table row: `| #N | title | assignee | status |`.
+
+    Single source of truth for the canonical row shape — used by canonicalize
+    (initial table) and by sync_missing_rows (drift-healing appends)."""
+    return f"| #{num} | {title} | {assignee} | {status} |"
+
+
+def append_rows(body: str, table: dict, row_lines: list[str]) -> str:
+    """Insert pre-rendered `row_lines` after the last data row of `table`.
+
+    `table` is a dict from find_*_status_tables. New rows land directly below
+    the table's existing rows (or after the header separator if the table has
+    none), so any narrative content below the table is preserved. The table's
+    line indices must still be valid for `body` (callers that rewrite cells in
+    place keep the line count stable, so this holds)."""
+    if not row_lines:
+        return body
+    lines = body.split("\n")
+    if table["rows"]:
+        insert_at = table["rows"][-1]["line_idx"] + 1
+    else:
+        insert_at = table["header_line_idx"] + 2  # past header + separator
+    lines[insert_at:insert_at] = row_lines
+    return "\n".join(lines)
+
+
+def _row_primary_num(row: dict) -> Optional[int]:
+    """First `#NNNN` issue ref in a row, or None. A row's frontmatter-order
+    anchor for ordered inserts."""
+    for cell in row["cells"]:
+        m = ISSUE_NUM_RE.search(cell)
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def sync_missing_rows(body: str, frontmatter_nums: list, issues_by_num: dict):
+    """Insert a canonical row for every frontmatter issue missing from the table.
+
+    Picks the canonical table when present (else the first status table),
+    diffs `frontmatter_nums` against the issue numbers already in that table,
+    and slots a row for each missing number into its FRONTMATTER-ORDER
+    position — a missing #487 lands above an existing #678 if frontmatter
+    lists 487 first, rather than tacking onto the end (issue #79). Existing
+    rows keep their relative order and are re-emitted verbatim, so the diff
+    only shows the inserted lines. Live title/assignee/status come from
+    `issues_by_num` (a {num: gh-issue-dict} map); a number with no fetched
+    data still gets a placeholder row so membership never silently drifts.
+
+    Returns `(new_body, rows_added)`. No-ops (returns body unchanged, 0) when
+    there is no table or nothing is missing."""
+    from lib.github_state import state_to_status_label, format_assignees
+
+    canonical = find_canonical_status_tables(body)
+    tables = canonical if canonical else find_all_status_tables(body)
+    if not tables:
+        return body, 0
+    table = tables[0]
+
+    existing = set()
+    for row in table["rows"]:
+        for cell in row["cells"]:
+            existing.update(int(m) for m in ISSUE_NUM_RE.findall(cell))
+
+    # frontmatter order is the canonical ranking; missing keeps that order.
+    rank = {n: i for i, n in enumerate(frontmatter_nums)}
+    missing = [n for n in frontmatter_nums if n not in existing]
+    if not missing:
+        return body, 0
+
+    new_row = {}
+    for num in missing:
+        issue = issues_by_num.get(num) or {}
+        new_row[num] = render_issue_row(
+            num, issue.get("title", "(not fetched)"),
+            format_assignees(issue),
+            state_to_status_label(issue.get("state")),
+        )
+
+    # No existing rows: nothing to interleave against — drop them all in
+    # frontmatter order after the header separator.
+    if not table["rows"]:
+        return append_rows(body, table, [new_row[n] for n in missing]), len(missing)
+
+    # Interleave: walk existing rows in place, flushing each pending missing
+    # row before the first existing row that outranks it. Existing rows with
+    # no frontmatter rank impose no constraint, so they never trigger a flush.
+    out, mi = [], 0
+    for row in table["rows"]:
+        r_rank = rank.get(_row_primary_num(row))
+        if r_rank is not None:
+            while mi < len(missing) and rank[missing[mi]] < r_rank:
+                out.append(new_row[missing[mi]])
+                mi += 1
+        out.append(row["raw"])
+    out.extend(new_row[n] for n in missing[mi:])
+
+    lines = body.split("\n")
+    first = table["rows"][0]["line_idx"]
+    last = table["rows"][-1]["line_idx"]
+    lines[first:last + 1] = out
+    return "\n".join(lines), len(missing)
+
+
+def _parse_row(line: str) -> list[str]:
+    s = line.strip()
+    if "|" not in s:
+        return []
+    if s.startswith("|"):
+        s = s[1:]
+    if s.endswith("|"):
+        s = s[:-1]
+    return s.split("|")
+
+
+def _is_separator(line: str) -> bool:
+    s = line.strip()
+    if not s:
+        return False
+    return all(c in "|-: " for c in s)

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

@@ -0,0 +1,109 @@
+"""Discover tracks under notes_root."""
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from lib.frontmatter import parse_file
+from lib.config import resolve_github_for_folder, resolve_local_path_for_folder
+
+
+@dataclass
+class Track:
+    path: Path
+    name: str
+    has_frontmatter: bool
+    needs_init: bool
+    needs_filing: bool
+    repo: Optional[str] = None
+    folder: Optional[str] = None
+    local_path: Optional[Path] = None
+    meta: dict = field(default_factory=dict)
+    body: str = ""
+
+
+def discover_tracks(cfg: dict) -> list[Track]:
+    """Walk notes_root for active (non-archived) .md files."""
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if not notes_root.exists():
+        return []
+    return _walk(notes_root, cfg, include_archive=False)
+
+
+def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
+    """Filter tracks by repo. Matches the config-key folder name OR the
+    `org/repo` GitHub slug, so users can pass either. Case-insensitive."""
+    k = key.lower()
+    return [t for t in tracks
+            if (t.folder and t.folder.lower() == k)
+            or (t.repo and t.repo.lower() == k)]
+
+
+def find_track_by_name(name: str, tracks: list[Track],
+                       *, active_only: bool = False) -> Optional[Track]:
+    """Find a single Track matching `name` (filename stem OR frontmatter `track`).
+
+    If active_only=True, only considers tracks with status active/in-progress/blocked.
+    Returns the single match or None. Used by every command that takes a track arg.
+    """
+    candidates = tracks
+    if active_only:
+        candidates = [t for t in candidates if t.has_frontmatter
+                      and t.meta.get("status") in ("active", "in-progress", "blocked")]
+    matching = [t for t in candidates if t.has_frontmatter
+                and (t.name == name or t.meta.get("track") == name)]
+    return matching[0] if len(matching) == 1 else None
+
+
+def discover_archived_tracks(cfg: dict) -> list[Track]:
+    """Walk notes_root for archived .md files only."""
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if not notes_root.exists():
+        return []
+    out = []
+    for md_path in sorted(notes_root.rglob("*.md")):
+        if "archive" not in md_path.parts:
+            continue
+        if md_path.name.startswith((".", "_")):
+            continue
+        out.append(_build_track(md_path, notes_root, cfg))
+    return out
+
+
+def _walk(notes_root: Path, cfg: dict, include_archive: bool) -> list[Track]:
+    out = []
+    for md_path in sorted(notes_root.rglob("*.md")):
+        if not include_archive and "archive" in md_path.parts:
+            continue
+        if md_path.name.startswith((".", "_")):
+            continue
+        out.append(_build_track(md_path, notes_root, cfg))
+    return out
+
+
+def _build_track(md_path: Path, notes_root: Path, cfg: dict) -> Track:
+    meta, body = parse_file(md_path)
+    has_fm = bool(meta)
+    rel = md_path.relative_to(notes_root)
+    in_subfolder = len(rel.parts) > 1
+    folder_name = rel.parts[0] if in_subfolder else None
+
+    repo = None
+    if has_fm and meta.get("github", {}).get("repo"):
+        repo = meta["github"]["repo"]
+    elif folder_name:
+        repo = resolve_github_for_folder(folder_name, cfg)
+
+    local = resolve_local_path_for_folder(folder_name, cfg) if folder_name else None
+
+    return Track(
+        path=md_path,
+        name=md_path.stem,
+        has_frontmatter=has_fm,
+        needs_init=in_subfolder and not has_fm,
+        needs_filing=not in_subfolder,
+        repo=repo,
+        folder=folder_name,
+        local_path=local,
+        meta=meta,
+        body=body,
+    )