r"(?:^|[\s`(\[])"

r"((?:internal|cmd|frontend/src|frontend/tests|scripts|native|specs|docs|\.github)"

r"/[\w./-]+"

r"\.(?:go|ts|tsx|vue|py|sh|ps1|yml|yaml|swift|md|json|iss|wxs))"

"""Go/TS/Python/Swift test-file naming. An implementation task is never

stem = os.path.splitext(basename)[0]

return (stem.endswith("_test") or stem.endswith(".test")

or stem.endswith("Tests") or stem.endswith(".spec")

"""Run a git command at the repo root; "" on failure."""

try:

r = subprocess.run(args, cwd=REPO_ROOT, capture_output=True, text=True)

except OSError:

return ""

"""(every tracked path, basename -> [paths]) — one `git ls-files` pass."""

files = [f for f in sh("git", "ls-files").splitlines() if f]

by_base: dict[str, list[str]] = defaultdict(list)

for f in files:

by_base[os.path.basename(f)].append(f)

"""A plausible stand-in for a missing cited path, or None.

base = os.path.basename(path)

stem, ext = os.path.splitext(base)

d = os.path.dirname(path)

cited_is_test = is_test_file(base)

if len(stem) >= 4:

siblings = []

for f in tracked:

if os.path.dirname(f) != d or not f.endswith(ext):

continue

fb = os.path.basename(f)

fs = os.path.splitext(fb)[0]

# `doctor.go` -> `doctor_cmd.go`, never `serve.go` -> `serveredition_*.go`.

if fs != stem and not fs.startswith(stem + "_"):

continue

# An implementation is not satisfied by its own test file.

if is_test_file(fb) and not cited_is_test:

continue

siblings.append(f)

if siblings:

return sorted(siblings, key=len)[0] + " [high]"

candidates = by_base.get(base, [])

if len(candidates) == 1:

top = path.split("/", 1)[0]

if candidates[0].split("/", 1)[0] == top:

return candidates[0] + " [medium]"

"""Is this identifier present anywhere in tracked source?"""

if sym in cache:

return cache[sym]

out = sh("git", "grep", "-l", "--fixed-strings", "--", sym)

cache[sym] = bool(out.strip())

"""(cited paths, cited symbols) from one task line."""

paths = PATH_RE.findall(text)

symbols = [s for s in SYMBOL_RE.findall(text)

if len(s) >= 8

and (SYMBOL_CAMEL.search(s) or s.count("_") >= 2)

and s.lower() not in SYMBOL_STOPLIST

and not s.endswith("_md")]

# A symbol that is really a filename fragment adds nothing.

symbols = [s for s in symbols if not any(s in p for p in paths)]

sym_cache: dict[str, bool]) -> dict:

tasks_md = os.path.join(SPECS_DIR, spec, "tasks.md")

findings: list[dict] = []

possibly_built: list[dict] = []

counts = {"ticked": 0, "unticked": 0, "ticked_with_evidence": 0}

if not os.path.isfile(tasks_md):

return {"spec": spec, "findings": [], "possibly_built": [], "counts": counts}

for lineno, line in enumerate(open(tasks_md, encoding="utf-8"), 1):

m = TASK_RE.match(line)

if not m:

continue

box, tid, text = m.group(1), m.group(2) or "?", m.group(3)

ticked = box in ("x", "X")

counts["ticked" if ticked else "unticked"] += 1

paths, symbols = extract(text)

if not paths and not symbols:

continue

found_symbols = [s for s in symbols if symbol_exists(s, sym_cache)]

missing_paths = [p for p in paths if p not in tracked]

if ticked:

if paths or symbols:

counts["ticked_with_evidence"] += 1

if not missing_paths:

continue # every cited path is present — nothing to say

# A found symbol proves the work exists regardless of where the

# spec *predicted* the file would live.

demoted = bool(found_symbols)

for p in missing_paths:

reloc = relocation_for(p, tracked, by_base)

if reloc:

target, _, conf = reloc.partition(" [")

conf = conf.rstrip("]") or "medium"

verdict = "RELOCATED"

detail = f"stale path; code lives at {target} (confidence: {conf})"

elif ever_existed(p):

verdict, detail = "REMOVED", "existed in git history, now deleted"

else:

verdict, detail = "UNRESOLVED", "never existed in git history"

if demoted and verdict == "UNRESOLVED":

verdict = "RELOCATED"

detail = (f"never existed, but cited symbol(s) "

f"{', '.join(found_symbols)} are present")

findings.append({

"spec": spec, "task": tid, "line": lineno, "path": p,

"verdict": verdict, "detail": detail,

"symbols_found": found_symbols,

})

else:

# Unticked, but everything it cites is already in the tree.

if paths and not missing_paths and (not symbols or found_symbols):

possibly_built.append({

"spec": spec, "task": tid, "line": lineno,

"paths": paths, "symbols_found": found_symbols,

})

return {"spec": spec, "findings": findings,

ap = argparse.ArgumentParser(

description="Verify that ticked spec tasks cite code that exists.")

ap.add_argument("specs", nargs="*", help="spec dir names (default: all)")

ap.add_argument("--json", action="store_true", help="machine-readable output")

ap.add_argument("--strict", action="store_true",

help="exit 1 if any ticked task is UNRESOLVED")

ap.add_argument("--quiet", action="store_true", help="summary only")

args = ap.parse_args()

specs = args.specs or sorted(

d for d in os.listdir(SPECS_DIR)

if os.path.isfile(os.path.join(SPECS_DIR, d, "tasks.md")))

tracked, by_base = build_tree_index()

sym_cache: dict[str, bool] = {}

results = [audit_spec(s, tracked, by_base, sym_cache) for s in specs]

findings = [f for r in results for f in r["findings"]]

possibly = [p for r in results for p in r["possibly_built"]]

unresolved = [f for f in findings if f["verdict"] == "UNRESOLVED"]

removed = [f for f in findings if f["verdict"] == "REMOVED"]

relocated = [f for f in findings if f["verdict"] == "RELOCATED"]

if args.json:

json.dump({"findings": findings, "possibly_built": possibly,

"summary": {"specs": len(specs), "unresolved": len(unresolved),

"removed": len(removed), "relocated": len(relocated),

"possibly_built": len(possibly)}},

sys.stdout, indent=2)

sys.stdout.write("\n")

return 1 if (args.strict and unresolved) else 0

if not args.quiet:

for group, title in ((unresolved, "UNRESOLVED — ticked, but the cited artifact was never built"),

(removed, "REMOVED — ticked, and the cited artifact was deleted")):

if group:

print(f"\n{title}:")

for f in group:

print(f" {f['spec']}/{f['task']} (line {f['line']})")

print(f" {f['path']} — {f['detail']}")

if relocated:

print(f"\nRELOCATED ({len(relocated)}) — work exists, the path reference is stale:")

for f in relocated[:10]:

print(f" {f['spec']}/{f['task']}: {f['path']} → {f['detail']}")

if len(relocated) > 10:

print(f" … and {len(relocated) - 10} more")

if possibly:

print(f"\nPOSSIBLY BUILT ({len(possibly)}) — unticked, but every cited artifact exists:")

for p in possibly[:10]:

print(f" {p['spec']}/{p['task']} (line {p['line']}): {', '.join(p['paths'][:2])}")

if len(possibly) > 10:

print(f" … and {len(possibly) - 10} more")

print(f"\n{len(specs)} specs · {len(unresolved)} unresolved · {len(removed)} removed "

f"· {len(relocated)} relocated (informational) · {len(possibly)} possibly-built")

if unresolved and not args.strict:

print("(report-only; pass --strict to fail on unresolved findings)")