@stylusnexus/work-plan 2026.6.9-1

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,248 @@
+"""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,
+    is_valid_git_repo,
+)
+
+
+@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 = ""
+    tier: Optional[str] = None
+
+
+def discover_tracks(cfg: dict) -> list[Track]:
+    """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]:
+    """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)]
+
+
+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 (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)]
+    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, and also scan each repo's
+    .work-plan/archive/ for shared archived tracks."""
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    out = []
+    if notes_root.exists():
+        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))
+
+    # Also scan shared repos' .work-plan/archive/
+    out.extend(_discover_shared_tracks(cfg, include_archive=True,
+                                        archive_only=True))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# 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 []
+    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
+        local_path = Path(entry["local"]).expanduser()
+        if not is_valid_git_repo(local_path):
+            continue
+        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 and README
+            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((".", "_")):
+            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,
+        tier="private",
+    )

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

@@ -0,0 +1,51 @@
+"""Pure verdict classification over gathered evidence. No I/O — fully unit-testable.
+
+Thresholds are module constants so a later phase can make them configurable
+without touching call sites.
+"""
+from dataclasses import dataclass
+from datetime import date
+from typing import Optional
+
+SHIPPED_PCT = 80.0      # >= this % of declared files satisfied -> shipped
+PARTIAL_PCT = 20.0      # >= this % -> partial
+BOXES_STALE_PCT = 50.0  # checked-box % below this on a shipped plan -> "boxes stale"
+DEAD_DAYS = 60          # 0 files satisfied AND untouched beyond this -> dead
+FOREIGN_RATIO = 0.7     # >= this fraction of declared paths outside repo -> foreign
+
+
+@dataclass
+class Verdict:
+    label: str      # shipped | partial | dead | foreign | manifest-less
+    glyph: str
+    rationale: str
+
+
+def classify(
+    score,
+    checkbox_done: int,
+    checkbox_total: int,
+    last_touched: Optional[date],
+    today: date,
+    dead_days: int = DEAD_DAYS,
+) -> Verdict:
+    if score.total == 0:
+        return Verdict("manifest-less", "\U0001f47b",
+                       "no file-manifest — needs LLM verdict (Phase 1b)")
+
+    pct = score.pct
+    files = f"{score.satisfied}/{score.total} declared files present"
+
+    if pct >= SHIPPED_PCT:
+        chk_pct = (checkbox_done / checkbox_total * 100.0) if checkbox_total else 0.0
+        stale = " (boxes stale)" if chk_pct < BOXES_STALE_PCT else ""
+        return Verdict("shipped", "✅", f"{files}{stale}")
+
+    if pct >= PARTIAL_PCT:
+        return Verdict("partial", "\U0001f7e1", files)
+
+    if last_touched is not None and (today - last_touched).days > dead_days:
+        age = (today - last_touched).days
+        return Verdict("dead", "\U0001f480", f"{files}, untouched {age}d")
+
+    return Verdict("partial", "\U0001f7e1", f"{files} (early)")

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

@@ -0,0 +1,39 @@
+"""Confirm-token gate so non-interactive callers (the VS Code extension) can
+surface the public-repo heads-up as their own dialog instead of a TTY prompt.
+
+needs_confirm() fails CLOSED: PUBLIC or unknown visibility both require confirm.
+Unknown visibility can be opted out of via cfg["assume_private_when_unknown"]=True
+(for all-private teams that want to avoid the prompt on transient gh failures).
+PUBLIC is never suppressed by this flag — the leak guarantee is unconditional.
+
+The token is a deterministic hash of (repo, track) — no randomness (3.9 stdlib,
+and stable so the re-invocation matches). It is not a security boundary; it just
+proves the caller saw the heads-up for THIS write."""
+import hashlib
+from lib.github_state import repo_visibility
+
+
+def needs_confirm(repo: str, cfg: dict = None) -> bool:
+    """True when a write to `repo` needs the public-repo confirm heads-up.
+
+    PUBLIC  → always True (never suppressed — the leak guarantee).
+    PRIVATE → False.
+    Unknown visibility (gh couldn't say / offline) → True (fail CLOSED) UNLESS
+    cfg opts out via `assume_private_when_unknown: true`, which lets an
+    all-private team avoid the prompt on transient gh-lookup failures. PUBLIC is
+    never affected by this flag."""
+    vis = repo_visibility(repo)
+    if vis == "PUBLIC":
+        return True
+    if vis == "PRIVATE":
+        return False
+    # vis is None → unknown / offline. Fail closed unless explicitly opted out.
+    if cfg and cfg.get("assume_private_when_unknown"):
+        return False
+    return True
+
+def make_token(repo: str, track: str) -> str:
+    return hashlib.sha256(f"{repo}::{track}".encode("utf-8")).hexdigest()[:16]
+
+def valid_token(token: str, repo: str, track: str) -> bool:
+    return bool(token) and token == make_token(repo, track)

package/skills/work-plan/tests/fixtures/notes_root/critforge/archive/shipped/old.md

@@ -0,0 +1,10 @@
+---
+track: old
+status: shipped
+launch_priority: P2
+github:
+  repo: stylusnexus/CritForge
+  issues: [50]
+---
+
+# Old shipped track

package/skills/work-plan/tests/fixtures/notes_root/critforge/example.md

@@ -0,0 +1,11 @@
+---
+track: example
+status: active
+launch_priority: P1
+github:
+  repo: stylusnexus/CritForge
+  issues: [100, 200]
+next_up: [100]
+---
+
+# Example

package/skills/work-plan/tests/fixtures/notes_root/critforge/no_frontmatter.md

@@ -0,0 +1 @@
+# No frontmatter

package/skills/work-plan/tests/fixtures/notes_root/loose_at_root.md

@@ -0,0 +1 @@
+# Loose

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

@@ -0,0 +1,14 @@
+---
+track: tabletop
+status: active
+launch_priority: P1
+github:
+  repo: stylusnexus/CritForge
+  issues: [4254, 4127]
+  branches: []
+next_up: [4254]
+---
+
+# Tabletop
+
+Body content.

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

@@ -0,0 +1,3 @@
+# Some plan
+
+Body only.

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

@@ -0,0 +1,9 @@
+# Track
+
+## Issues
+
+| # | Title | Status |
+|---|---|---|
+| #4254 | admin polls | 🔲 Open |
+| #4127 | dice roller | ✅ Shipped |
+| #925 | wild magic | 🟡 In PR (#4137) |