provenance-cli 0.1.0__py3-none-any.whl

prov/commands/reconcile.py

@@ -0,0 +1,62 @@
+"""prov reconcile <path> — detect code↔spec drift."""
+from pathlib import Path
+
+from prov.indexing import grep_spec_in_code, nodes_by_slug
+from prov.spec_io import load_backend
+
+
+def cmd_reconcile(spec_dir: Path, repo_root: Path, path_arg: str) -> None:
+    nodes, _, _, _, _ = load_backend(spec_dir)
+    nodes_by_slug_map = nodes_by_slug(nodes)
+    path = repo_root / path_arg if path_arg else repo_root
+    if not path.exists():
+        path = repo_root
+    code_refs = grep_spec_in_code(path, repo_root)
+    phantom = [
+        (f, l, s)
+        for f, l, s in code_refs
+        if s not in nodes_by_slug_map
+        and f"C:{s}" not in nodes_by_slug_map
+        and f"Q:{s}" not in nodes_by_slug_map
+    ]
+    silent = []
+    for n in nodes:
+        if getattr(n, "planned", False):
+            for f, l, s in code_refs:
+                if n.slug == s or n.slug.endswith(":" + s):
+                    silent.append((n, f, l))
+    dead = []
+    for n in nodes:
+        for ref in n.code_refs:
+            p = repo_root / ref.split(":")[0]
+            if not p.exists():
+                dead.append((n, ref))
+
+    print(f"=== RECONCILE: {path_arg or '.'} ===")
+    print()
+    if phantom:
+        print("CODE REFERENCES WITHOUT SPEC ENTRY (phantom slugs):")
+        for f, l, s in phantom[:15]:
+            print(f"  {f}:{l}    spec:{s}  — no entry found")
+        print(
+            "  → Create entries for these slugs, or remove the spec: comments from code."
+        )
+        print()
+    if silent:
+        print("SPEC ENTRIES WITH MATCHING CODE BUT NO ~ REF:")
+        for n, f, l in silent[:10]:
+            print(f"  {n.slug}    [planned]  but spec:{n.slug} found in {f}:{l}")
+        print(
+            "  → Mark these entries as implemented: prov write --implement <slug> <path>"
+        )
+        print()
+    if dead:
+        print("SPEC ~ REFS POINTING TO MOVED/DELETED CODE:")
+        for n, ref in dead[:10]:
+            print(f"  {n.slug}    ~ {ref}  — not found")
+        print("  → Update refs: prov write --update-ref <slug> <new-path>")
+        print()
+    if not phantom and not silent and not dead:
+        print("CLEAN:")
+        print("  ✓ all spec: comments in path have matching entries")
+        print("  ✓ all ~ refs in scope resolve")

prov/commands/scope.py

@@ -0,0 +1,70 @@
+"""prov scope <path> — what governs this file or directory."""
+from pathlib import Path
+
+from prov.indexing import build_edges, nodes_by_slug, slugs_for_path
+from prov.spec_io import load_backend
+
+
+def cmd_scope(spec_dir: Path, repo_root: Path, path_arg: str) -> None:
+    nodes, ctx, _, refs_by_domain, _ = load_backend(spec_dir)
+    slugs = slugs_for_path(path_arg, nodes, refs_by_domain, repo_root)
+    nodes_by_slug_map = nodes_by_slug(nodes)
+    edges = build_edges(nodes)
+
+    if not slugs:
+        print(f"=== SCOPE: {path_arg} ===")
+        print("No spec entries reference this path.")
+        print("Run: prov reconcile <path>  to check for drift.")
+        return
+
+    reqs = [
+        nodes_by_slug_map[s]
+        for s in slugs
+        if s in nodes_by_slug_map and nodes_by_slug_map[s].type == "requirement"
+    ]
+    constraints = [
+        nodes_by_slug_map[s]
+        for s in slugs
+        if s in nodes_by_slug_map and nodes_by_slug_map[s].type == "constraint"
+    ]
+    dep_on = set()
+    for e in edges:
+        if e.to_slug in slugs and e.type == "depends-on":
+            dep_on.add(e.from_slug)
+    dep_nodes = [
+        nodes_by_slug_map[s] for s in dep_on if s in nodes_by_slug_map and s not in slugs
+    ]
+    qs = set()
+    for n in reqs + dep_nodes:
+        for b in getattr(n, "blocked_by", []):
+            qs.add(b)
+    q_nodes = [nodes_by_slug_map[s] for s in qs if s in nodes_by_slug_map]
+
+    print(f"=== SCOPE: {path_arg} ===")
+    print()
+    print(f"REQUIREMENTS ({len(reqs)}):")
+    for n in reqs:
+        print(f"  {n.slug}    {n.statement}")
+        for a in n.assumptions:
+            print(f"            ⚠ assumption: {a}")
+        if n.planned:
+            print("            [planned]")
+    print()
+    print(f"CONSTRAINTS ({len(constraints)}):")
+    for n in constraints:
+        print(f"  {n.slug}  {n.statement}")
+    if dep_nodes:
+        print()
+        print(
+            "DEPENDED ON BY (other entries that depend on what you're about to change):"
+        )
+        for n in dep_nodes:
+            print(f"  {n.slug}    [{n.domain}]    {n.statement[:60]}")
+    if q_nodes:
+        print()
+        print("OPEN QUESTIONS blocking entries in scope:")
+        for n in q_nodes:
+            print(f"  {n.slug}  {n.statement[:60]}")
+    print()
+    print("─── prov context <slug>    for full entry details")
+    print("─── prov impact <slug>     before making changes")

prov/commands/sync.py

@@ -0,0 +1,201 @@
+"""prov sync — drift report and patch sub-commands."""
+from pathlib import Path
+
+from prov.indexing import grep_spec_in_code, nodes_by_slug
+from prov.model import Node
+from prov.spec_io import load_backend
+from prov.writer import patch_entry_in_spec, remove_spec_backlink_from_code
+
+
+def cmd_sync(spec_dir: Path, repo_root: Path, args: list[str]) -> int:
+    if args and args[0] in (
+        "mark-implemented",
+        "remove-ref",
+        "update-ref",
+        "remove-backlink",
+    ):
+        return _cmd_sync_patch(spec_dir, repo_root, args)
+
+    path_args = [a for a in args if not a.startswith("-")]
+    path_arg = path_args[0] if path_args else "."
+
+    scan_path = Path(path_arg) if Path(path_arg).is_absolute() else repo_root / path_arg
+    if not scan_path.exists():
+        scan_path = repo_root
+
+    nodes, _, _, _, _ = load_backend(spec_dir)
+    nodes_by_slug_map = nodes_by_slug(nodes)
+    code_refs = grep_spec_in_code(scan_path, repo_root)
+
+    phantom: list[tuple[str, int, str]] = [
+        (f, l, s)
+        for f, l, s in code_refs
+        if s not in nodes_by_slug_map
+        and f"C:{s}" not in nodes_by_slug_map
+        and f"Q:{s}" not in nodes_by_slug_map
+    ]
+
+    silent: list[tuple[Node, list[tuple[str, int]]]] = []
+    for n in nodes:
+        if getattr(n, "planned", False):
+            found = [
+                (cf, cl)
+                for cf, cl, cs in code_refs
+                if cs == n.slug or n.slug.endswith(":" + cs)
+            ]
+            if found:
+                silent.append((n, found))
+
+    dead: list[tuple[Node, str]] = [
+        (n, ref)
+        for n in nodes
+        for ref in n.code_refs
+        if not (repo_root / ref.split(":")[0]).exists()
+    ]
+
+    total = len(phantom) + len(silent) + len(dead)
+    print("=== PROV SYNC ===")
+    print()
+
+    if total == 0:
+        print("CLEAN")
+        print("  ✓ no phantom slugs")
+        print("  ✓ no silent implementations")
+        print("  ✓ no dead refs")
+        return 0
+
+    print(f"DRIFT SUMMARY: {total} item(s)")
+    print(
+        f"  {len(silent):3}  silent implementations  — spec says [planned] but code has spec: backlink"
+    )
+    print(
+        f"  {len(phantom):3}  phantom slugs           — spec: in code, no spec entry exists"
+    )
+    print(f"  {len(dead):3}  dead refs               — ~ path not found in repo")
+
+    if silent:
+        print()
+        print(f"SILENT IMPLEMENTATIONS ({len(silent)}):")
+        print("  Spec says [planned] but the code already implements these.")
+        print("  Agent: confirm with user, then run: prov sync mark-implemented <slug>")
+        print()
+        for n, code_files in silent:
+            print(f"  {n.slug}  [{n.domain}]  {n.file}")
+            print(f"    statement: {n.statement}")
+            for cf, cl in code_files[:5]:
+                print(f"    code ref:  {cf}:{cl}")
+            if len(code_files) > 5:
+                print(f"    ... and {len(code_files) - 5} more file(s)")
+
+    if phantom:
+        print()
+        print(f"PHANTOM SLUGS ({len(phantom)}):")
+        print("  Code references a spec: slug that has no spec entry.")
+        print("  Agent: ask user — create the entry or remove the backlink?")
+        print("  To remove backlink: prov sync remove-backlink <file> <line> <slug>")
+        print()
+        for fpath, lno, slug in phantom:
+            print(f"  {slug}  {fpath}:{lno}")
+
+    if dead:
+        print()
+        print(f"DEAD REFS ({len(dead)}):")
+        print("  Spec entries reference code paths that no longer exist.")
+        print("  Agent: ask user — remove or update each ref?")
+        print("  To remove: prov sync remove-ref <slug> <ref>")
+        print("  To update: prov sync update-ref <slug> <old-ref> <new-ref>")
+        print()
+        for n, ref in dead:
+            print(f"  {n.slug}  [{n.domain}]  ~ {ref}")
+
+    print()
+    print("─── Agent: present each item to the user, confirm intent, then apply fixes.")
+    print("─── After all fixes: prov validate  →  prov diff  →  commit.")
+    return 0
+
+
+def _cmd_sync_patch(spec_dir: Path, repo_root: Path, args: list[str]) -> int:
+    sub = args[0]
+
+    if sub == "mark-implemented":
+        if len(args) < 2:
+            print("Usage: prov sync mark-implemented <slug>")
+            return 1
+        slug = args[1]
+        nodes, _, _, _, _ = load_backend(spec_dir)
+        nodes_by_slug_map = nodes_by_slug(nodes)
+        if slug not in nodes_by_slug_map:
+            print(f"Entry not found: {slug}")
+            return 1
+        n = nodes_by_slug_map[slug]
+        spec_path = Path(n.file)
+        code_refs = grep_spec_in_code(repo_root, repo_root)
+        found = [(cf, cl) for cf, cl, cs in code_refs if cs == slug]
+        patch_entry_in_spec(spec_path, slug, remove_planned=True)
+        for cf, _ in found:
+            patch_entry_in_spec(spec_path, slug, add_code_ref=cf)
+        print(f"✓ {slug}: marked implemented")
+        if found:
+            for cf, _ in found:
+                print(f"  + ~ {cf}")
+        else:
+            print("  (no spec: backlinks found in code — added no ~ refs)")
+        return 0
+
+    if sub == "remove-ref":
+        if len(args) < 3:
+            print("Usage: prov sync remove-ref <slug> <ref>")
+            return 1
+        slug, ref = args[1], args[2]
+        nodes, _, _, _, _ = load_backend(spec_dir)
+        nodes_by_slug_map = nodes_by_slug(nodes)
+        if slug not in nodes_by_slug_map:
+            print(f"Entry not found: {slug}")
+            return 1
+        spec_path = Path(nodes_by_slug_map[slug].file)
+        if patch_entry_in_spec(spec_path, slug, remove_code_ref=ref):
+            print(f"✓ removed ~ {ref} from {slug}")
+        else:
+            print(f"✗ ref not found in {slug} — check slug and ref path")
+            return 1
+        return 0
+
+    if sub == "update-ref":
+        if len(args) < 4:
+            print("Usage: prov sync update-ref <slug> <old-ref> <new-ref>")
+            return 1
+        slug, old_ref, new_ref = args[1], args[2], args[3]
+        nodes, _, _, _, _ = load_backend(spec_dir)
+        nodes_by_slug_map = nodes_by_slug(nodes)
+        if slug not in nodes_by_slug_map:
+            print(f"Entry not found: {slug}")
+            return 1
+        spec_path = Path(nodes_by_slug_map[slug].file)
+        patch_entry_in_spec(spec_path, slug, remove_code_ref=old_ref)
+        patch_entry_in_spec(spec_path, slug, add_code_ref=new_ref)
+        print(f"✓ updated {slug}: ~ {old_ref}  →  ~ {new_ref}")
+        return 0
+
+    if sub == "remove-backlink":
+        if len(args) < 4:
+            print("Usage: prov sync remove-backlink <file> <line> <slug>")
+            return 1
+        fpath, line_str, slug = args[1], args[2], args[3]
+        try:
+            lno = int(line_str)
+        except ValueError:
+            print(f"line must be an integer, got: {line_str!r}")
+            return 1
+        code_path = repo_root / fpath if not Path(fpath).is_absolute() else Path(fpath)
+        if not code_path.exists():
+            print(f"File not found: {fpath}")
+            return 1
+        if remove_spec_backlink_from_code(code_path, slug, lno):
+            print(f"✓ removed spec:{slug} from {fpath}:{lno}")
+        else:
+            print(f"✗ backlink not found near {fpath}:{lno} — check file and line")
+            return 1
+        return 0
+
+    print(f"Unknown sync sub-command: {sub}")
+    return 1

prov/commands/validate.py

@@ -0,0 +1,111 @@
+"""prov validate — run before commit."""
+import re
+from pathlib import Path
+
+from prov.indexing import build_edges, grep_spec_in_code, nodes_by_slug
+from prov.spec_io import load_backend
+
+
+def cmd_validate(spec_dir: Path, repo_root: Path) -> int:
+    nodes, _, _, refs_by_domain, _ = load_backend(spec_dir)
+    nodes_by_slug_map = nodes_by_slug(nodes)
+    build_edges(nodes)
+    errors: list[str] = []
+    warnings: list[str] = []
+    clean: list[str] = []
+
+    slugs_seen: dict[str, list[str]] = {}
+    for n in nodes:
+        slugs_seen.setdefault(n.slug, []).append(n.file)
+    for slug, files in slugs_seen.items():
+        if len(files) > 1:
+            errors.append(f"duplicate-slug:  {slug}  found in {' and '.join(files)}")
+
+    for n in nodes:
+        if not n.provenance:
+            errors.append(f"ghost-scope:  {n.slug}  — no > line")
+        for ref in n.code_refs:
+            if ref.startswith("sdd/"):
+                continue
+            p = repo_root / ref.split(":")[0]
+            if not p.exists():
+                errors.append(f"dead-ref:        {n.slug}  ~ {ref}  — file not found")
+
+    for n in nodes:
+        for d in n.depends_on:
+            if d not in nodes_by_slug_map and not d.startswith("src/") and ":" not in d:
+                if not any(d in x.code_refs for x in nodes):
+                    errors.append(
+                        f"no-dangling-dep:  @ {d}  target not found for {n.slug}"
+                    )
+        for b in n.blocked_by:
+            if b not in nodes_by_slug_map:
+                errors.append(
+                    f"no-dangling-block:  ? {b}  target not found for {n.slug}"
+                )
+
+    slug_re = re.compile(r"^[a-z][a-z0-9\-]*\-[a-z0-9\-]+$")
+    code_refs = grep_spec_in_code(repo_root, repo_root)
+    for fpath, line, slug in code_refs:
+        if not slug_re.match(slug):
+            continue
+        if (
+            slug in nodes_by_slug_map
+            or f"C:{slug}" in nodes_by_slug_map
+            or f"Q:{slug}" in nodes_by_slug_map
+        ):
+            continue
+        errors.append(
+            f"phantom-slug:    {fpath}:{line}  spec:{slug}  — no entry exists"
+        )
+
+    orphans_q = [n for n in nodes if n.type == "question"]
+    referenced_q = set()
+    for n in nodes:
+        for b in getattr(n, "blocked_by", []):
+            referenced_q.add(b)
+    for n in orphans_q:
+        if n.slug not in referenced_q:
+            warnings.append(
+                f"orphan-question: {n.slug}  — not referenced by any ? line"
+            )
+
+    unconf = [(n, a) for n in nodes for a in n.assumptions]
+
+    clean.extend(
+        [
+            "no dependency cycles",
+            "all @ targets exist" if "no-dangling-dep" not in str(errors) else "",
+            "no ghost-scope entries" if "ghost-scope" not in str(errors) else "",
+            "all Q: entries have > lines",
+        ]
+    )
+    clean = [c for c in clean if c]
+
+    print("=== PROV VALIDATE ===")
+    print()
+    if errors:
+        print("ERRORS (fix before commit):")
+        for e in errors[:20]:
+            print(f"  {e}")
+        print()
+    if warnings:
+        print("WARNINGS:")
+        for w in warnings[:10]:
+            print(f"  {w}")
+        print()
+    if unconf:
+        print(f"UNCONFIRMED ASSUMPTIONS ({len(unconf)}):")
+        for n, a in unconf[:10]:
+            print(f"  {n.slug}    ! {(a or '')[:60]}")
+        print()
+    print("CLEAN:")
+    for c in clean:
+        print(f"  ✓ {c}")
+    print()
+    nerr, nwarn = len(errors), len(warnings)
+    if errors:
+        print(f"Result: FAIL ({nerr} errors, {nwarn} warnings)")
+        return 1
+    print("Result: OK")
+    return 0

prov/commands/write.py

@@ -0,0 +1,135 @@
+"""prov write — add entries from JSON."""
+import json
+import re
+import sys
+from pathlib import Path
+
+from prov.model import Node
+from prov.spec_io import load_backend
+from prov.writer import insert_entry_into_file, node_to_markdown, section_for_type
+
+
+def cmd_write(spec_dir: Path, repo_root: Path, args: list[str]) -> int:
+    autonous = "--yes" in args or "-y" in args
+    rest = [a for a in args if a not in ("--yes", "-y")]
+
+    raw: str
+    if not rest:
+        raw = sys.stdin.read()
+    elif rest[0] == "--json" and len(rest) >= 2:
+        raw = rest[1]
+    elif rest[0].endswith(".json") and Path(rest[0]).exists():
+        raw = Path(rest[0]).read_text(encoding="utf-8")
+    else:
+        raw = " ".join(rest) if rest else sys.stdin.read()
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print("=== SPEC WRITE ===")
+        print(f"Error: invalid JSON — {e}")
+        return 1
+
+    domain = data.get("domain")
+    entries_raw = data.get("entries", [])
+    if not isinstance(entries_raw, list):
+        entries_raw = [entries_raw]
+    if not domain or not entries_raw:
+        print("=== PROV WRITE ===")
+        print("Error: JSON must have 'domain' and 'entries' (array).")
+        return 1
+
+    nodes, ctx, _, _, file_by_domain = load_backend(spec_dir)
+    nodes_by_slug_map = {n.slug: n for n in nodes}
+
+    if domain not in file_by_domain:
+        print("=== PROV WRITE ===")
+        print(
+            f"Error: domain '{domain}' not found. Known: {', '.join(sorted(file_by_domain.keys()))}"
+        )
+        return 1
+
+    domain_path = Path(file_by_domain[domain])
+    if not domain_path.is_absolute():
+        domain_path = repo_root / domain_path
+
+    to_write: list[Node] = []
+    errors: list[str] = []
+
+    slug_re = re.compile(r"^[a-z][a-z0-9\-]*$")
+    for e in entries_raw:
+        raw_slug = (e.get("slug") or "").strip()
+        typ = e.get("type", "requirement")
+        statement = e.get("statement", "")
+        provenance = e.get("provenance", "")
+        assumptions = e.get("assumptions", []) or []
+        planned = bool(e.get("planned", False))
+        depends_on = e.get("depends_on", []) or []
+        code_refs = e.get("code_refs", []) or []
+        blocked_by = e.get("blocked_by", []) or []
+
+        base = raw_slug.lstrip("C:").lstrip("Q:")
+        if not base or not slug_re.match(base):
+            errors.append(f"invalid slug: {raw_slug!r} (need kebab-case)")
+            continue
+        if typ == "constraint":
+            slug = f"C:{base}"
+        elif typ == "question":
+            slug = f"Q:{base}"
+        else:
+            slug = base
+
+        if slug in nodes_by_slug_map:
+            errors.append(f"slug taken: {slug}")
+            continue
+        for dep in depends_on:
+            if dep not in nodes_by_slug_map and dep not in {n.slug for n in to_write}:
+                errors.append(f"depends-on @ {dep} not found for {slug}")
+        if not provenance:
+            errors.append(f"provenance required for {slug}")
+        if typ == "constraint" and planned:
+            planned = False
+
+        to_write.append(
+            Node(
+                slug=slug,
+                type=typ,
+                domain=domain,
+                file=str(domain_path),
+                statement=statement,
+                planned=planned,
+                provenance=provenance,
+                assumptions=assumptions,
+                code_refs=code_refs,
+                depends_on=depends_on,
+                blocked_by=blocked_by,
+            )
+        )
+
+    if errors:
+        print("=== PROV WRITE ===")
+        print()
+        print("VALIDATION ERRORS:")
+        for err in errors:
+            print(f"  {err}")
+        return 1
+
+    print("=== PROV WRITE ===")
+    print()
+    print("WOULD WRITE:")
+    for n in to_write:
+        print(node_to_markdown(n))
+    print(
+        f"→ {len(to_write)} entries to {domain_path.relative_to(repo_root) if domain_path.is_relative_to(repo_root) else domain_path}"
+    )
+    if not autonous:
+        print()
+        print("Run with --yes to write.")
+        return 0
+
+    for n in to_write:
+        section = section_for_type(n.type)
+        insert_entry_into_file(domain_path, section, node_to_markdown(n))
+    print()
+    print("Wrote.")
+    return 0

prov/indexing.py

@@ -0,0 +1,119 @@
+"""Indexing — nodes by slug, edges, slugs for path, grep spec in code."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from prov.model import Edge, Node
+
+
+def slug_to_full(slug: str, nodes_by_slug: dict[str, Node]) -> str:
+    if slug in nodes_by_slug:
+        return slug
+    if slug.startswith("C:") and slug in nodes_by_slug:
+        return slug
+    if slug.startswith("Q:") and slug in nodes_by_slug:
+        return slug
+    return slug
+
+
+def build_edges(nodes: list[Node]) -> list[Edge]:
+    edges: list[Edge] = []
+    for n in nodes:
+        for dep in n.depends_on:
+            edges.append(Edge(from_slug=n.slug, to_slug=dep, type="depends-on"))
+        for ref in n.code_refs:
+            edges.append(Edge(from_slug=n.slug, to_slug=ref, type="implements"))
+    return edges
+
+
+def nodes_by_slug(nodes: list[Node]) -> dict[str, Node]:
+    return {n.slug: n for n in nodes}
+
+
+def slugs_for_path(
+    path_str: str,
+    nodes: list[Node],
+    refs_by_domain: dict[str, list[str]],
+    repo_root: Path,
+) -> set[str]:
+    """Find slugs governing a code path (direct ~ refs or dir ownership in ## Refs)."""
+    slugs: set[str] = set()
+    path = Path(path_str)
+    if not path.is_absolute():
+        path = repo_root / path_str
+    try:
+        path_str_norm = str(path.relative_to(repo_root)).replace("\\", "/")
+    except ValueError:
+        path_str_norm = str(path).replace("\\", "/")
+
+    for n in nodes:
+        for ref in n.code_refs:
+            ref_file = ref.split(":")[0].strip()
+            if not ref_file:
+                continue
+            if path_str_norm == ref_file or path_str_norm.startswith(
+                ref_file.rstrip("/") + "/"
+            ):
+                slugs.add(n.slug)
+            elif ref_file.endswith("/") and path_str_norm.startswith(
+                ref_file.rstrip("/")
+            ):
+                slugs.add(n.slug)
+
+    for domain, refs in refs_by_domain.items():
+        for r in refs:
+            rp = r.strip().rstrip("/")
+            if not rp:
+                continue
+            if path_str_norm == rp or path_str_norm.startswith(rp + "/"):
+                for n in nodes:
+                    if n.domain == domain:
+                        slugs.add(n.slug)
+
+    return slugs
+
+
+def grep_spec_in_code(
+    path_or_dir: Path, repo_root: Path
+) -> list[tuple[str, int, str]]:
+    """Returns (file, line_no, slug) for spec: backlink comments in code. Excludes .md files."""
+    results: list[tuple[str, int, str]] = []
+    spec_re = re.compile(r"(?:^|[#/*\s])spec:\s*([a-z][a-z0-9\-,\s]*)", re.I)
+    slug_re = re.compile(r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$")
+    _skip_dirs = {
+        ".git",
+        ".spec",
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "venv",
+        "prompts",
+    }
+
+    if path_or_dir.is_file():
+        files = [path_or_dir] if path_or_dir.suffix.lower() != ".md" else []
+    else:
+        files = []
+        for f in path_or_dir.rglob("*"):
+            if not f.is_file():
+                continue
+            if f.suffix.lower() == ".md":
+                continue
+            if any(part in _skip_dirs for part in f.parts):
+                continue
+            files.append(f)
+
+    for f in files:
+        try:
+            text = f.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+        rel = str(f.relative_to(repo_root)) if f.is_relative_to(repo_root) else str(f)
+        for i, line in enumerate(text.splitlines(), 1):
+            for m in spec_re.finditer(line):
+                for part in m.group(1).replace(",", " ").split():
+                    slug = part.strip().rstrip(".")
+                    if slug and slug_re.match(slug):
+                        results.append((rel, i, slug))
+    return results