@stylusnexus/work-plan 2026.6.9-1

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

@@ -0,0 +1,180 @@
+"""Local git queries + time helpers."""
+import subprocess
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+
+def gap_seconds_to_label(seconds: int) -> str:
+    """'Nm ago' / 'Nh ago' / 'Nd ago'."""
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m ago"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h ago"
+    days = hours // 24
+    return f"{days}d ago"
+
+
+def parse_iso_timestamp(s: str) -> datetime:
+    if "T" in s:
+        return datetime.strptime(s, "%Y-%m-%dT%H:%M")
+    return datetime.strptime(s, "%Y-%m-%d")
+
+
+def current_branch(repo_path: Path) -> Optional[str]:
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "branch", "--show-current"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def has_uncommitted(repo_path: Path) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "status", "--short"],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def uncommitted_file_count(repo_path: Path) -> int:
+    if not repo_path or not Path(repo_path).exists():
+        return 0
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "status", "--short"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return 0
+    return len([l for l in proc.stdout.splitlines() if l.strip()])
+
+
+def commits_ahead(branch_name: str, base: str, repo_path: Path) -> int:
+    if not repo_path or not Path(repo_path).exists():
+        return 0
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-list", "--count", f"{base}..{branch_name}"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return 0
+    try:
+        return int(proc.stdout.strip())
+    except ValueError:
+        return 0
+
+
+def branch_exists(branch_name: str, repo_path: Path) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-parse", "--verify", branch_name],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0
+
+
+def _has_recent_commits(branch_name: str, repo_path: Path, hours: int = 24) -> bool:
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    if not branch_exists(branch_name, repo_path):
+        return False
+    since = (datetime.now() - timedelta(hours=hours)).strftime("%Y-%m-%dT%H:%M:%S")
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", branch_name,
+         f"--since={since}", "--pretty=format:%H"],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def branch_in_progress(branch_name: str, repo_path: Path) -> bool:
+    """Detect 'in-progress':
+    - It's the current branch AND has uncommitted changes, OR
+    - It has commits in the last 24 hours.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    if not branch_exists(branch_name, repo_path):
+        return False
+    cur = current_branch(repo_path)
+    if cur == branch_name and has_uncommitted(repo_path):
+        return True
+    return _has_recent_commits(branch_name, repo_path, hours=24)
+
+
+def last_commit_date(branch_name: str, repo_path: Path) -> Optional[datetime]:
+    """Most recent commit timestamp on branch (naive)."""
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    if not branch_exists(branch_name, repo_path):
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", "-1", branch_name, "--pretty=format:%cI"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        s = proc.stdout.strip().split("+")[0].split("Z")[0]
+        return datetime.fromisoformat(s)
+    except (ValueError, IndexError):
+        return None
+
+
+def path_last_commit_date(rel_path: str, repo_path: Path) -> Optional[datetime]:
+    """Timestamp of the most recent commit touching `rel_path` (naive datetime)."""
+    if not repo_path or not Path(repo_path).exists():
+        return None
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log", "-1", "--pretty=format:%cI", "--", rel_path],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        s = proc.stdout.strip().split("+")[0].split("Z")[0]
+        return datetime.fromisoformat(s)
+    except (ValueError, IndexError):
+        return None
+
+
+def path_committed_since(rel_path: str, since: date, repo_path: Path) -> bool:
+    """True if `rel_path` has any commit on/around `since` or later (a datetime.date).
+
+    `git log --since` resolves to local midnight and can drop commits made on the
+    plan date itself (timezone-dependent) — the common case where a plan is written
+    and its files land the same day. We widen the window by one day so same-day
+    Modify commits are reliably counted; including the prior day is an acceptable
+    cost for a liveness heuristic.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    window_start = since - timedelta(days=1)
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "log",
+         f"--since={window_start.isoformat()}", "--pretty=format:%H", "--", rel_path],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and bool(proc.stdout.strip())
+
+
+def git_mv(src_rel: str, dst_rel: str, repo_path: Path) -> bool:
+    """git-mv `src_rel` -> `dst_rel` (both repo-relative), creating the dest
+    directory first. Returns True on success. History-preserving."""
+    if not repo_path or not Path(repo_path).exists():
+        return False
+    (Path(repo_path) / dst_rel).parent.mkdir(parents=True, exist_ok=True)
+    proc = subprocess.run(
+        ["git", "-C", str(repo_path), "mv", src_rel, dst_rel],
+        capture_output=True, text=True,
+    )
+    return proc.returncode == 0

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

@@ -0,0 +1,296 @@
+"""Query GitHub via `gh`."""
+import json
+import re
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from typing import Iterable, Optional
+
+PRIORITY_LABELS = ("priority/P0", "priority/P1", "priority/P2", "priority/P3")
+DEFAULT_PRIORITY = "P3"
+
+MAX_FETCH_WORKERS = 8
+
+_GH_ISSUE_FIELDS = "number,state,labels,title,milestone,url,closedAt,body,updatedAt,assignees"
+
+_REPO_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
+GQL_CHUNK = 100  # issues per GraphQL query; GitHub GraphQL complexity budget ~5000 pts/query, 100 issueOrPullRequest nodes is well within it
+
+
+def fetch_issue(repo: str, number: int) -> Optional[dict]:
+    """Fetch a single issue via gh. Returns parsed dict on success, None on failure.
+    Never raises — a missing `gh` binary or any subprocess error yields None."""
+    try:
+        proc = subprocess.run(
+            ["gh", "issue", "view", str(number),
+             "--repo", repo,
+             "--json", _GH_ISSUE_FIELDS],
+            capture_output=True, text=True,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def fetch_issues(repo: str, issue_numbers: Iterable[int]) -> list[dict]:
+    """Fetch state of multiple issues via gh (sequential). Unchanged semantics."""
+    nums = list(issue_numbers)
+    if not nums:
+        return []
+    results = []
+    for num in nums:
+        result = fetch_issue(repo, num)
+        if result is not None:
+            results.append(result)
+    return results
+
+
+def fetch_issues_concurrent(jobs: Iterable[tuple], max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch multiple (repo, number) pairs concurrently.
+
+    Dedupes jobs (first-seen order preserved). Returns a dict keyed by
+    (repo, number) containing only successful fetches (None results omitted).
+    Empty jobs -> {}.
+    """
+    unique_jobs = list(dict.fromkeys(jobs))
+    if not unique_jobs:
+        return {}
+    workers = min(max_workers, len(unique_jobs))
+    result: dict[tuple, dict] = {}
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(fetch_issue, repo, num): (repo, num)
+                   for repo, num in unique_jobs}
+        for future, key in futures.items():
+            issue = future.result()
+            if issue is not None:
+                result[key] = issue
+    return result
+
+
+def _normalize_gql_node(node) -> Optional[dict]:
+    """Reshape a GraphQL issueOrPullRequest node into the REST-ish shape export_model
+    expects (assignees as [{login}], milestone as {title}|None). None for a null node.
+    On success returns a dict with keys: number, title, state, assignees, milestone."""
+    if not node:
+        return None
+    assignees = [{"login": a.get("login")} for a in
+                 ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
+    ms = node.get("milestone")
+    return {
+        "number": node.get("number"),
+        "title": node.get("title", ""),
+        "state": node.get("state", "OPEN"),
+        "assignees": assignees,
+        "milestone": {"title": ms["title"]} if ms and ms.get("title") else None,
+    }
+
+
+def _gql_query(owner: str, name: str, numbers: list) -> str:
+    fields = ("number title state assignees(first: 10) { nodes { login } } milestone { title }")
+    aliases = "\n".join(
+        f'  i{n}: issueOrPullRequest(number: {int(n)}) {{ '
+        f'... on Issue {{ {fields} }} ... on PullRequest {{ {fields} }} }}'
+        for n in numbers
+    )
+    return f'query {{ repository(owner: "{owner}", name: "{name}") {{\n{aliases}\n}} }}'
+
+
+def fetch_repo_issues_graphql(repo: str, numbers, chunk: int = GQL_CHUNK,
+                              max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch exactly `numbers` from `repo` via batched GraphQL (issueOrPullRequest, so
+    PRs are included). Returns {number: normalized_issue} for those found. Never raises;
+    missing/null/errored numbers are simply omitted (caller may fall back per-issue)."""
+    try:
+        nums = list(dict.fromkeys(int(n) for n in numbers))
+    except (ValueError, TypeError):
+        return {}
+    if not nums or not _REPO_RE.match(repo or ""):
+        return {}
+    owner, name = repo.split("/", 1)
+    chunks = [nums[i:i + chunk] for i in range(0, len(nums), chunk)]
+
+    def _run(batch):
+        try:
+            proc = subprocess.run(
+                ["gh", "api", "graphql", "-f", "query=" + _gql_query(owner, name, batch)],
+                capture_output=True, text=True,
+            )
+        except Exception:
+            return {}
+        if proc.returncode != 0 or not proc.stdout.strip():
+            return {}
+        try:
+            data = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            return {}
+        repo_obj = ((data.get("data") or {}).get("repository") or {})
+        out = {}
+        for node in repo_obj.values():
+            norm = _normalize_gql_node(node)
+            if norm and norm.get("number") is not None:
+                out[norm["number"]] = norm
+        return out
+
+    result = {}
+    with ThreadPoolExecutor(max_workers=min(max_workers, len(chunks))) as ex:
+        for part in ex.map(_run, chunks):
+            result.update(part)
+    return result
+
+
+def fetch_export_issues(repo_to_numbers: dict, max_workers: int = MAX_FETCH_WORKERS) -> dict:
+    """Fetch referenced issues for the viewer export with minimal gh calls: batched
+    GraphQL per repo (only the referenced numbers; includes PRs), run concurrently
+    across repos, with a per-issue fallback for anything GraphQL didn't return.
+    Returns {(repo, number): issue_dict}. Never raises."""
+    repos = [r for r, nums in repo_to_numbers.items() if r and nums]
+    if not repos:
+        return {}
+    try:
+        with ThreadPoolExecutor(max_workers=min(max_workers, len(repos))) as ex:
+            gql_by_repo = dict(zip(repos, ex.map(
+                lambda r: fetch_repo_issues_graphql(r, repo_to_numbers[r], max_workers=max_workers),
+                repos)))
+    except Exception:
+        gql_by_repo = {r: {} for r in repos}
+    result, missing = {}, []
+    for repo, numbers in repo_to_numbers.items():
+        if not repo or not numbers:
+            continue
+        got = gql_by_repo.get(repo, {})
+        for n in numbers:
+            if n in got:
+                result[(repo, n)] = got[n]
+            else:
+                missing.append((repo, n))
+    if missing:
+        result.update(fetch_issues_concurrent(missing, max_workers=max_workers))
+    return result
+
+
+def fetch_open_issues(repo: str, limit: int = 1000) -> list[dict]:
+    """All OPEN issues for `repo` as gh rows ({number,title,assignees,milestone,state}).
+    One `gh issue list` call. Never raises — returns [] on any error/bad repo."""
+    if not _REPO_RE.match(repo or ""):
+        return []
+    try:
+        proc = subprocess.run(
+            ["gh", "issue", "list", "--repo", repo,
+             "--state", "open",
+             "--json", "number,title,state,assignees,milestone",
+             "--limit", str(limit)],
+            capture_output=True, text=True,
+        )
+    except Exception:
+        return []
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return []
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return []
+
+
+def fetch_recent_issues(repo: str, since_iso: str, extra_labels: list[str] = None) -> list[dict]:
+    """Fetch issues created since `since_iso` (date YYYY-MM-DD)."""
+    search = f"created:>={since_iso}"
+    cmd = ["gh", "issue", "list", "--repo", repo,
+           "--state", "all",
+           "--search", search,
+           "--limit", "50",
+           "--json", "number,title,labels,createdAt,milestone,url"]
+    if extra_labels:
+        for lab in extra_labels:
+            cmd.extend(["--label", lab])
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        return []
+    return json.loads(proc.stdout) if proc.stdout.strip() else []
+
+
+_VIS_CACHE: dict = {}
+
+
+def repo_visibility(repo: str) -> Optional[str]:
+    """Best-effort repo visibility ('PUBLIC'/'PRIVATE') via gh; None if unknown.
+    Memoized per process. Never raises — unknown visibility is a valid answer."""
+    if not repo:
+        return None
+    if repo in _VIS_CACHE:
+        return _VIS_CACHE[repo]
+    proc = subprocess.run(
+        ["gh", "repo", "view", repo, "--json", "visibility"],
+        capture_output=True, text=True,
+    )
+    vis = None
+    if proc.returncode == 0 and proc.stdout.strip():
+        try:
+            vis = json.loads(proc.stdout).get("visibility")
+        except json.JSONDecodeError:
+            vis = None
+    _VIS_CACHE[repo] = vis
+    return vis
+
+
+def extract_priority(labels: list[dict]) -> str:
+    label_names = {l["name"] for l in labels}
+    for p in PRIORITY_LABELS:
+        if p in label_names:
+            return p.split("/")[1]
+    return DEFAULT_PRIORITY
+
+
+def short_milestone(milestone) -> str:
+    """Extract a compact milestone tag from a gh milestone object.
+
+    gh returns milestone as `{"title": "v0.4.0 — MVP Go-Live Gate", ...}` or null.
+    The leading token (e.g. `v0.4.0`) is what tracks declare in
+    `milestone_alignment:`, so it's the natural form to show in tight per-issue
+    lines. Returns "" when milestone is missing or has no title.
+    """
+    if not milestone:
+        return ""
+    title = milestone.get("title") if isinstance(milestone, dict) else None
+    if not title:
+        return ""
+    return title.split()[0] if title.split() else ""
+
+
+def format_assignees(issue: dict) -> str:
+    """Render a canonical-table assignee cell from an issue's assignees.
+
+    Returns `@login, @login` for one or more assignees, or `—` when there are
+    none (or the issue dict is missing). Matches the placeholder used by
+    canonicalize so appended rows are visually consistent.
+    """
+    assignees = (issue or {}).get("assignees") or []
+    logins = [f"@{a['login']}" for a in assignees if a.get("login")]
+    return ", ".join(logins) if logins else "—"
+
+
+def state_to_status_label(state: str) -> str:
+    """Map a GitHub issue/PR state to a human-readable status label.
+
+    CLOSED and MERGED both map to ✅ Shipped (gh treats PRs as a kind of
+    issue, so issue-API responses can return MERGED for PR refs).
+    """
+    s = (state or "OPEN").upper()
+    if s in ("CLOSED", "MERGED"):
+        return "✅ Shipped"
+    return "🔲 Open"
+
+
+def create_issue(repo: str, title: str, body: str) -> Optional[str]:
+    """Open a GitHub issue via `gh issue create`. Returns the issue URL, or None
+    on failure. Reuses the user's `gh` auth; never touches tokens."""
+    proc = subprocess.run(
+        ["gh", "issue", "create", "--repo", repo, "--title", title, "--body", body],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None

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

@@ -0,0 +1,45 @@
+"""Pick the docs that need an LLM verdict and gather evidence for the judgment.
+
+Two kinds of candidate mechanical scoring can't resolve:
+  - manifest-less: prose docs (design specs) with no Create/Modify/Test paths.
+  - ambiguous: a manifest exists but <AMBIGUOUS_PCT of files are satisfied — the
+    suspicious "0/N looks unstarted but was recently touched" cases, usually
+    Modify-heavy plans the file-existence signal under-counts.
+"""
+from lib import git_state
+
+AMBIGUOUS_PCT = 20.0
+EXCERPT_CHARS = 1500
+
+
+def select_candidates(rows: list) -> list:
+    """From evaluated rows, return those needing an LLM verdict."""
+    out = []
+    for r in rows:
+        if r["verdict"] == "manifest-less":
+            out.append(r)
+        elif r["files_declared"] > 0:
+            pct = r["files_present"] / r["files_declared"] * 100.0
+            if pct < AMBIGUOUS_PCT:
+                out.append(r)
+    return out
+
+
+def _first_title(text: str) -> str:
+    for line in text.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return "(no title)"
+
+
+def gather_evidence(doc, repo_root) -> dict:
+    """Build the evidence dict the model uses to judge one doc."""
+    text = doc.path.read_text(encoding="utf-8", errors="replace")
+    last = git_state.path_last_commit_date(doc.rel, repo_root)
+    return {
+        "rel": doc.rel,
+        "kind": doc.kind,
+        "title": _first_title(text),
+        "last_touched": last.date().isoformat() if last else None,
+        "excerpt": text[:EXCERPT_CHARS],
+    }

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

@@ -0,0 +1,164 @@
+"""Parse a plan's declared file-manifest + checkboxes, and score it against
+the filesystem and git. The honest completion signal is which declared files
+actually exist / were committed — not the (unreliable) checkbox state.
+"""
+import re
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Callable, Optional
+
+# Matches:  Create: `path`  /  Modify: `path:120-145`  /  Test: `path`
+PATH_RE = re.compile(r"\b(Create|Modify|Test):\s*`([^`]+)`")
+# Trailing line spec: ':120', ':120-145', or comma-joined ':104-115,217-247'
+_RANGE_RE = re.compile(r":\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$")
+_CHK_DONE = re.compile(r"^\s*- \[x\]", re.I | re.M)
+_CHK_TODO = re.compile(r"^\s*- \[ \]", re.M)
+_DATE_RE = re.compile(r"(\d{4})-(\d{2})-(\d{2})")
+
+
+@dataclass(frozen=True)
+class DeclaredPath:
+    kind: str   # "create" | "modify" | "test"
+    path: str   # repo-relative, line-range stripped
+
+
+def strip_range(p: str) -> str:
+    """'src/foo.ts:120-145' -> 'src/foo.ts'; bare paths unchanged."""
+    return _RANGE_RE.sub("", p.strip())
+
+
+def parse_declared_paths(text: str) -> list:
+    """Extract declared file paths. First kind seen per path wins (dedup)."""
+    seen = {}  # path -> kind
+    for kind, raw in PATH_RE.findall(text):
+        p = strip_range(raw)
+        if "/" not in p:                       # skip bare tokens / commands
+            continue
+        if p.startswith(("http", "git ")):     # skip urls / shell
+            continue
+        seen.setdefault(p, kind.lower())
+    return [DeclaredPath(kind=k, path=p) for p, k in seen.items()]
+
+
+def count_checkboxes(text: str) -> tuple:
+    """Return (done, total) markdown task checkboxes."""
+    done = len(_CHK_DONE.findall(text))
+    todo = len(_CHK_TODO.findall(text))
+    return done, done + todo
+
+
+def plan_date_from_filename(filename: str) -> Optional[date]:
+    """Pull a YYYY-MM-DD prefix out of a plan filename, if present."""
+    m = _DATE_RE.search(filename)
+    if not m:
+        return None
+    try:
+        return date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+    except ValueError:
+        return None
+
+
+def is_in_tree(path: str, repo_root) -> bool:
+    """True if a declared path resolves inside repo_root. A '~'-rooted path, an
+    absolute path elsewhere, or a '..'-escaping path is out-of-tree."""
+    if path.startswith("~"):
+        return False
+    root = Path(repo_root).resolve()
+    p = Path(path)
+    target = p.resolve() if p.is_absolute() else (root / p).resolve()
+    try:
+        target.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def out_of_tree_ratio(decls: list, repo_root) -> float:
+    """Fraction of declared paths resolving outside repo_root (0.0 if none declared)."""
+    if not decls:
+        return 0.0
+    out = sum(1 for d in decls if not is_in_tree(d.path, repo_root))
+    return out / len(decls)
+
+
+@dataclass
+class ManifestScore:
+    total: int
+    satisfied: int
+    by_kind: dict   # {"create": (sat, tot), "modify": (sat, tot), "test": (sat, tot)}
+
+    @property
+    def pct(self) -> Optional[float]:
+        return (self.satisfied / self.total * 100.0) if self.total else None
+
+
+def _path_satisfied(d, exists, committed_since) -> bool:
+    return committed_since(d.path) if d.kind == "modify" else exists(d.path)
+
+
+def score_manifest(
+    decls: list,
+    repo_root: Path,
+    plan_date: Optional[date],
+    *,
+    exists: Optional[Callable] = None,
+    committed_since: Optional[Callable] = None,
+) -> ManifestScore:
+    """Score declared paths. `Create`/`Test` count if the file exists now;
+    `Modify` counts only if the file was committed on/after `plan_date`
+    (existence alone is meaningless for a pre-existing modify target).
+
+    `exists(rel)->bool` and `committed_since(rel)->bool` are injectable for
+    offline testing; defaults wire to the filesystem and git.
+    """
+    if exists is None:
+        exists = lambda rel: (Path(repo_root) / rel).exists()
+    if committed_since is None:
+        from lib import git_state
+        # Deliberate degradation: with no plan date we can't ask "committed since
+        # when?", so a Modify falls back to mere existence. This can over-count an
+        # undated plan's Modify targets — accepted because superpowers plans carry a
+        # YYYY-MM-DD filename prefix, so the dateless path is rare in practice.
+        committed_since = (
+            (lambda rel: git_state.path_committed_since(rel, plan_date, repo_root))
+            if plan_date is not None
+            else (lambda rel: (Path(repo_root) / rel).exists())
+        )
+
+    by = {"create": [0, 0], "modify": [0, 0], "test": [0, 0]}
+    satisfied = 0
+    for d in decls:
+        by[d.kind][1] += 1
+        if _path_satisfied(d, exists, committed_since):
+            by[d.kind][0] += 1
+            satisfied += 1
+    return ManifestScore(
+        total=len(decls),
+        satisfied=satisfied,
+        by_kind={k: tuple(v) for k, v in by.items()},
+    )
+
+
+def unsatisfied_paths(
+    decls: list,
+    repo_root: Path,
+    plan_date: Optional[date],
+    *,
+    exists: Optional[Callable] = None,
+    committed_since: Optional[Callable] = None,
+) -> list:
+    """Return the declared paths that are NOT satisfied (missing / not committed).
+
+    Same satisfaction rule and injectable predicates as `score_manifest`.
+    """
+    if exists is None:
+        exists = lambda rel: (Path(repo_root) / rel).exists()
+    if committed_since is None:
+        from lib import git_state
+        committed_since = (
+            (lambda rel: git_state.path_committed_since(rel, plan_date, repo_root))
+            if plan_date is not None
+            else (lambda rel: (Path(repo_root) / rel).exists())
+        )
+    return [d for d in decls if not _path_satisfied(d, exists, committed_since)]