@stylusnexus/work-plan 2026.6.9 → 2026.6.10-2

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

@@ -1,12 +1,35 @@
 """Shared CLI helpers: prompts and arg parsing."""
+import sys
+
+
+def _stdin_is_interactive() -> bool:
+    """True only when stdin is a real terminal we can block on for a reply.
+
+    When the CLI is launched with stdin wired to a pipe or socket that stays
+    open but never delivers a line — e.g. the VS Code extension spawning
+    `work_plan.py` — `input()` blocks forever (no data, no EOF). A closed pipe
+    raises EOFError and is handled; an *idle open* one hangs. Guarding on
+    `isatty()` lets the prompt helpers fall back to their default instead of
+    deadlocking. Non-interactive callers should pass an explicit flag
+    (`--yes`, `--draft`) rather than rely on the prompt.
+    """
+    try:
+        return bool(sys.stdin) and sys.stdin.isatty()
+    except (ValueError, AttributeError):
+        # stdin closed/detached, or replaced by an object without isatty.
+        return False
 
 
 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.
+    Returns the stripped input, or `default` if EOF, blank, or there is no
+    interactive terminal to read from.
     """
     print(message)
+    if not _stdin_is_interactive():
+        print(f"(no interactive terminal — using default {default!r})")
+        return default
     try:
         line = input().strip()
     except EOFError:
@@ -15,7 +38,12 @@ def prompt_input(message: str, default: str = "") -> str:
 
 
 def prompt_lines() -> list[str]:
-    """Read lines from stdin until blank line or EOF. Returns list of non-blank lines."""
+    """Read lines from stdin until blank line or EOF. Returns list of non-blank lines.
+
+    With no interactive terminal, returns an empty list rather than blocking.
+    """
+    if not _stdin_is_interactive():
+        return []
     out = []
     try:
         while True:
@@ -29,11 +57,14 @@ def prompt_lines() -> list[str]:
 
 
 def prompt_yes_no(message: str = "Apply? [y/N]") -> bool:
-    """Print prompt and read y/N. Treats EOF (no stdin) as no.
+    """Print prompt and read y/N. Treats EOF or no terminal as no.
 
     Returns True only if user explicitly types 'y' (case-insensitive).
     """
     print(message)
+    if not _stdin_is_interactive():
+        print("(no interactive terminal — defaulting to no)")
+        return False
     try:
         choice = input().strip().lower()
     except EOFError:
@@ -49,14 +80,25 @@ def parse_flags(args: list[str], known: set[str]) -> tuple[dict, list[str]]:
     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.
+      - flags_dict: {"--all": True, "--repo": "myproject", ...} 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 = []
+    end_of_opts = False
     for arg in args:
+        # A bare `--` ends option parsing: everything after it is positional,
+        # even if it begins with `--`. Lets callers (e.g. the VS Code extension)
+        # pass a GitHub-derived value like a `--repo`-named track as a plain
+        # positional instead of having it misparsed as a flag (#194).
+        if end_of_opts:
+            positional.append(arg)
+            continue
+        if arg == "--":
+            end_of_opts = True
+            continue
         if not arg.startswith("--"):
             positional.append(arg)
             continue

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

@@ -104,12 +104,102 @@ def update_row_status(body: str, issue_num: int, new_status: str) -> str:
     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 |`.
+def render_issue_row(num: int, title: str, assignee: str, status: str,
+                     milestone: Optional[str] = None) -> str:
+    """Render a canonical issue-table row.
+
+    Single source of truth for the canonical row shape. With `milestone=None`
+    (the default) renders the 4-column form `| #N | title | assignee | status |`
+    used by narrative tables and sync_missing_rows appends. Pass a milestone
+    string (possibly empty) to render the 5-column canonical form
+    `| #N | title | milestone | assignee | status |` used by render_canonical_table
+    (#101). An empty string still renders the column — distinct from None, which
+    drops it."""
+    if milestone is None:
+        return f"| #{num} | {title} | {assignee} | {status} |"
+    return f"| #{num} | {title} | {milestone} | {assignee} | {status} |"
+
+
+def render_canonical_table(issue_nums: list, issues_by_num: dict,
+                           milestone_alignment=None) -> str:
+    """Render the canonical issues block: heading, marker, and ONE table.
+
+    The table carries a `Milestone` column and is ordered active-milestone-first
+    (the shared `milestone_sort_key`): issues whose milestone matches the track's
+    `milestone_alignment` come first, then other milestones grouped by label,
+    then no-milestone issues last; a blank divider row separates each group.
+
+    Deliberately a SINGLE table (not per-milestone sub-tables): it round-trips
+    through refresh-md, which re-derives this whole block on every run, so the
+    rendered order can't decay (#101). The blank divider row has no `#NNNN`
+    ref, so the table parsers skip it.
+
+    Returns the block string (heading + marker + table); callers add the
+    trailing `---` separator via insert_canonical_block."""
+    from lib.github_state import (
+        short_milestone, format_assignees, state_to_status_label,
+    )
+    from lib.export_model import group_issues_by_milestone
+
+    lines = [
+        "## Issues (canonical)",
+        "",
+        f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
+        "",
+        "| # | Title | Milestone | Assignee | Status |",
+        "|---|---|---|---|---|",
+    ]
+
+    norm = []
+    for num in sorted(issue_nums):
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm.append({"number": num, "milestone": ms, "_gh": gh})
+
+    groups = group_issues_by_milestone(norm, milestone_alignment)
+    for gi, (label, issues) in enumerate(groups):
+        if gi > 0:
+            lines.append("| | | | | |")  # blank divider row between milestone groups
+        for it in issues:
+            gh = it["_gh"]
+            lines.append(render_issue_row(
+                it["number"], gh.get("title", "(not fetched)"),
+                format_assignees(gh), state_to_status_label(gh.get("state")),
+                milestone=it["milestone"] or "",
+            ))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def strip_canonical_block(body: str) -> str:
+    """Remove an existing canonical-table block from the top of the body.
 
-    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} |"
+    The block runs from the `## Issues (canonical)` heading (or the marker if
+    the heading is absent) through the next `\\n---\\n` separator. Returns the
+    body unchanged when no marker is present."""
+    if CANONICAL_MARKER not in body:
+        return body
+    heading_idx = body.find("## Issues (canonical)")
+    marker_idx = body.find(CANONICAL_MARKER)
+    start = heading_idx if 0 <= heading_idx < marker_idx else marker_idx
+    sep_idx = body.find("\n---\n", marker_idx)
+    if sep_idx == -1:
+        end = body.find("\n", marker_idx) + 1
+    else:
+        end = sep_idx + len("\n---\n")
+    return body[:start] + body[end:].lstrip("\n")
+
+
+def insert_canonical_block(body: str, table_md: str, replace: bool = False) -> str:
+    """Prepend `table_md` (a render_canonical_table block) at the top of body,
+    followed by a `---` separator. With replace=True, strip any existing
+    canonical block first (so refresh-md re-derive and canonicalize --force
+    produce identical output)."""
+    if replace:
+        body = strip_canonical_block(body)
+    body_stripped = body.lstrip("\n")
+    leading = body[: len(body) - len(body_stripped)]
+    return leading + table_md + "\n---\n\n" + body_stripped
 
 
 def append_rows(body: str, table: dict, row_lines: list[str]) -> str:

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

@@ -1,10 +1,42 @@
-"""Discover tracks under notes_root."""
+"""Discover tracks under notes_root and shared .work-plan/ dirs."""
+import sys
 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
+from lib.config import (
+    resolve_github_for_folder,
+    resolve_local_path_for_folder,
+    is_valid_git_repo,
+)
+from lib.git_state import parse_iso_timestamp
+
+_PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+
+
+def priority_rank(meta: dict) -> int:
+    """Rank a track's launch_priority for ascending sort: P0<P1<P2<P3<anything.
+
+    Unknown / missing values (e.g. "—" or absent) sort after all known ranks.
+    """
+    return _PRIORITY_RANK.get(meta.get("launch_priority"), len(_PRIORITY_RANK))
+
+
+def recency_sort_key(meta: dict) -> float:
+    """Sort key for last_touched recency (most recent first when sorted ascending).
+
+    Returns the negative POSIX timestamp so that a plain ascending sort puts the
+    most-recently-touched track first. Tracks with no (or unparseable)
+    last_touched return +inf, sorting them LAST.
+    """
+    raw = meta.get("last_touched")
+    if not raw:
+        return float("inf")
+    try:
+        return -parse_iso_timestamp(raw).timestamp()
+    except (ValueError, TypeError):
+        return float("inf")
 
 
 @dataclass
@@ -19,14 +51,37 @@ class Track:
     local_path: Optional[Path] = None
     meta: dict = field(default_factory=dict)
     body: str = ""
+    tier: Optional[str] = None
 
 
 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)
+    """Walk notes_root for active (non-archived) .md files, then union with
+    shared tracks from each configured repo's .work-plan/ directory.
+    Shared wins on (repo, name) collisions.
+    """
+    private = _discover_private_tracks(cfg, include_archive=False)
+    shared = _discover_shared_tracks(cfg, include_archive=False)
+
+    # Build lookup for shared tracks keyed by (repo, name)
+    shared_keys: dict = {}
+    for t in shared:
+        key = (t.repo, t.name)
+        shared_keys[key] = t
+
+    # Merge: private tracks that have no colliding shared track are kept
+    merged = list(shared)
+    for t in private:
+        key = (t.repo, t.name)
+        if key in shared_keys:
+            print(
+                f"WARN: track {t.name!r} (repo={t.repo!r}) exists in both shared"
+                f" ({shared_keys[key].path}) and private ({t.path}); using shared.",
+                file=sys.stderr,
+            )
+        else:
+            merged.append(t)
+
+    return merged
 
 
 def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
@@ -38,49 +93,188 @@ def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
             or (t.repo and t.repo.lower() == k)]
 
 
-def find_track_by_name(name: str, tracks: list[Track],
-                       *, active_only: bool = False) -> Optional[Track]:
+class AmbiguousTrackError(Exception):
+    """Raised when a track name matches more than one track across repos."""
+
+    def __init__(self, name: str, candidates: list[Track]):
+        self.name = name
+        self.candidates = candidates
+        repos = [f"  {t.name} (repo: {t.repo or t.folder!r})" for t in candidates]
+        super().__init__(
+            f"Track {name!r} is ambiguous — found in {len(candidates)} repos:\n"
+            + "\n".join(repos)
+            + f"\nUse --repo=<key> or '{name}@<repo>' to disambiguate."
+        )
+
+
+def parse_track_repo_arg(arg: str) -> tuple:
+    """Split 'trackname@repokey' into (trackname, repokey); return (arg, None) if no @."""
+    if "@" in arg:
+        name, _, repo = arg.rpartition("@")
+        return (name, repo) if name else (arg, None)
+    return (arg, None)
+
+
+def find_track_by_name(
+    name: str, tracks: list[Track],
+    *, active_only: bool = False, repo: Optional[str] = None
+) -> Optional[Track]:
     """Find a single Track matching `name` (filename stem OR frontmatter `track`).
 
+    If repo is given, first filter to tracks matching that repo (folder key or
+    GitHub slug, case-insensitive). Then find a single name match.
+
     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.
+
+    Returns the single match or None (0 matches).
+    Raises AmbiguousTrackError if 2+ matches remain after filtering.
     """
     candidates = tracks
+    if repo:
+        candidates = filter_tracks_by_repo(candidates, repo)
     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
+    if len(matching) <= 1:
+        return matching[0] if matching else None
+    raise AmbiguousTrackError(name, matching)
 
 
 def discover_archived_tracks(cfg: dict) -> list[Track]:
-    """Walk notes_root for archived .md files only."""
+    """Walk notes_root for archived .md files, and also scan each repo's
+    .work-plan/archive/ for shared archived tracks.
+
+    Deduplicates by (repo, name): shared wins over private, same as
+    discover_tracks for active tracks.
+    """
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    private_archived: list[Track] = []
+    if notes_root.exists():
+        for md_path in sorted(notes_root.rglob("*.md")):
+            if "archive" not in md_path.parts:
+                continue
+            # '-' prefix rejected so a `--repo.md` file can't become a `--repo`
+            # track that the CLI misparses as a flag (#194).
+            if md_path.name.startswith((".", "_", "-")):
+                continue
+            private_archived.append(_build_track(md_path, notes_root, cfg))
+
+    shared_archived = _discover_shared_tracks(cfg, include_archive=True,
+                                              archive_only=True)
+
+    # Build lookup for shared tracks keyed by (repo, name)
+    shared_keys: dict = {}
+    for t in shared_archived:
+        key = (t.repo, t.name)
+        shared_keys[key] = t
+
+    # Merge: shared wins on collision
+    merged = list(shared_archived)
+    for t in private_archived:
+        key = (t.repo, t.name)
+        if key in shared_keys:
+            print(
+                f"WARN: archived track {t.name!r} (repo={t.repo!r}) exists in"
+                f" both shared ({shared_keys[key].path}) and private"
+                f" ({t.path}); using shared.",
+                file=sys.stderr,
+            )
+        else:
+            merged.append(t)
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _discover_private_tracks(cfg: dict, include_archive: bool) -> list[Track]:
     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:
+    return _walk(notes_root, cfg, include_archive=include_archive)
+
+
+def _discover_shared_tracks(cfg: dict, include_archive: bool = False,
+                             archive_only: bool = False) -> list[Track]:
+    """Walk each configured repo's local clone .work-plan/ directory."""
+    out: list[Track] = []
+    repos = cfg.get("repos", {})
+    for folder_key, entry in repos.items():
+        if not entry or not entry.get("local"):
             continue
-        if md_path.name.startswith((".", "_")):
+        local_path = Path(entry["local"]).expanduser()
+        if not is_valid_git_repo(local_path):
             continue
-        out.append(_build_track(md_path, notes_root, cfg))
+        github_repo = entry.get("github")
+        notes_dir = local_path / ".work-plan"
+        if not notes_dir.is_dir():
+            continue
+        for md_path in sorted(notes_dir.rglob("*.md")):
+            # Skip dotfiles, README, and dash-led names (a `--repo.md` file
+            # would otherwise become a `--repo` track the CLI misparses, #194).
+            if md_path.name.startswith((".", "-")) or md_path.name == "README.md":
+                continue
+            in_archive = "archive" in md_path.relative_to(notes_dir).parts
+            if archive_only and not in_archive:
+                continue
+            if not include_archive and in_archive:
+                continue
+            out.append(_build_shared_track(
+                md_path, folder_key, github_repo, local_path
+            ))
     return out
 
 
+def _build_shared_track(md_path: Path, folder_key: str,
+                         github_repo: Optional[str], local_path: Path) -> Track:
+    """Build a Track from a shared .work-plan/ markdown file."""
+    meta, body = parse_file(md_path)
+    has_fm = bool(meta)
+
+    # Single-owner rule: if frontmatter disagrees with folder config, warn and
+    # use the folder's configured github repo (never the frontmatter value).
+    if has_fm and meta.get("github", {}).get("repo"):
+        fm_repo = meta["github"]["repo"]
+        if fm_repo != github_repo:
+            print(
+                f"WARN: shared track {md_path.name!r} frontmatter github.repo"
+                f" differs from folder config; using folder {github_repo!r}",
+                file=sys.stderr,
+            )
+
+    return Track(
+        path=md_path,
+        name=md_path.stem,
+        has_frontmatter=has_fm,
+        needs_init=False,
+        needs_filing=False,
+        repo=github_repo,
+        folder=folder_key,
+        local_path=local_path,
+        meta=meta,
+        body=body,
+        tier="shared",
+    )
+
+
 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((".", "_")):
+        # '-' prefix rejected so a `--repo.md` file can't become a `--repo`
+        # track that the CLI misparses as a flag (#194).
+        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:
+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)
@@ -106,4 +300,5 @@ def _build_track(md_path: Path, notes_root: Path, cfg: dict) -> Track:
         local_path=local,
         meta=meta,
         body=body,
+        tier="private",
     )

package/skills/work-plan/tests/fixtures/notes_root/{critforge → myproject}/archive/shipped/old.md

@@ -3,7 +3,7 @@ track: old
 status: shipped
 launch_priority: P2
 github:
-  repo: stylusnexus/CritForge
+  repo: your-org/myproject
   issues: [50]
 ---
 

package/skills/work-plan/tests/fixtures/notes_root/{critforge → myproject}/example.md

@@ -3,7 +3,7 @@ track: example
 status: active
 launch_priority: P1
 github:
-  repo: stylusnexus/CritForge
+  repo: your-org/myproject
   issues: [100, 200]
 next_up: [100]
 ---

package/skills/work-plan/tests/fixtures/track_with_frontmatter.md

@@ -3,7 +3,7 @@ track: tabletop
 status: active
 launch_priority: P1
 github:
-  repo: stylusnexus/CritForge
+  repo: your-org/myproject
   issues: [4254, 4127]
   branches: []
 next_up: [4254]