@techierathore/techieflow 1.0.4 → 1.1.0

package/.tfcore/utils/tf-ci-repro.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# tf-ci-repro.sh — reproduce a CI job here the way a fresh runner runs it (Lekhak TF-019, 2026-09-30).
+#
+#   bash .tfcore/utils/tf-ci-repro.sh [<workflow.yml>] [--job <id>] [--list] [--keep] [--run-setup]
+#
+# Run from the repository root. A developer machine hides CI failures in its package caches and its
+# build output: Lekhak's CI failed with NETSDK1112 because the win-x64 runtime pack was never
+# downloaded, while the same commands passed locally where the pack was already cached. A local run
+# with warm caches is therefore no proof that a CI failure is fixed. This script copies the repository
+# without anything .gitignore ignores, to a folder outside it, points every package cache it knows
+# (NuGet, npm, yarn, pnpm, pip, Go, Gradle, Maven) at an empty folder, and runs the job's `run:` steps
+# in the runner's shell, stopping at the first failure. A Windows job runs Windows-side from WSL.
+# `uses:` steps, steps that need a secret and steps that only install tools on the machine are
+# skipped, each with the reason. --list prints the plan and runs nothing; --keep keeps the copy.
+# Prints ONE verdict line last:
+#   PASS     job <id>: <n> run step(s) passed on a clean copy with empty caches (…) — logs <dir>   exit 0
+#   FAIL     job <id>: step <n> "<name>" failed (exit N) with empty caches — <first error> — log <file>   exit 1
+#   NOT-RUN  <why: no workflow, several jobs, a macOS job off a Mac …>                         exit 2
+# PyYAML is used when installed; without it (a stock Mac) a built-in reader takes the workflow.
+# Logs: tests/.artifacts/ci-repro/<UTC time>/step-NN.log. The first run downloads every package, so
+# it takes as long as a cold CI restore.
+set -uo pipefail
+case "${1:-}" in -h|--help) sed -n '2,21p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+exec python3 "$(dirname "${BASH_SOURCE[0]}")/tf-ci-repro.py" "$@"

package/.tfcore/utils/tf-devguide-list.py

@@ -50,9 +50,16 @@ def cfg(key, default):
 PRUNE = {"bin", "obj", "node_modules", ".git", ".artifacts", "OldDocs", "dist", ".tfcore", ".claude", ".opencode", "packages", "TestResults"}
 
 
+# The folders a project keeps its code in, in the order tf-verify-boot.sh looks (Lekhak TF-014: Lekhak's
+# is source/, and --update counted only src/).
+CODE_ROOTS = ("src", "source")
+
+
 def walk(root, exts, skip_samples=False):
     for d, dirs, files in os.walk(root):
-        dirs[:] = [x for x in dirs if x not in PRUNE]   # prune in place: never descend into build output
+        # prune in place: never descend into build output, nor into any hidden folder (.tfbuild, .vs,
+        # .playwright …), which holds tool output, never a page (Lekhak TF-014)
+        dirs[:] = [x for x in dirs if x not in PRUNE and not x.startswith(".")]
         dd = d.replace("\\", "/") + "/"
         if any(s in dd for s in SKIP):
             continue
@@ -60,20 +67,28 @@ def walk(root, exts, skip_samples=False):
             continue
         for f in files:
             if f.lower().endswith(exts):
-                yield os.path.join(d, f).replace("\\", "/").lstrip("./")
+                p = os.path.join(d, f).replace("\\", "/")
+                # only a leading "./" goes: lstrip("./") also ate the dot of a hidden folder, and
+                # .tfbuild/… became tfbuild/…, which does not exist (Lekhak TF-014)
+                yield p[2:] if p.startswith("./") else p
+
+
+def code_files(exts, skip_samples=True):
+    """Every file with these extensions under the project's code folders (src/, source/)."""
+    for r in CODE_ROOTS:
+        if os.path.isdir(r):
+            yield from walk(r, exts, skip_samples=skip_samples)
 
 
 def roles_from_usageguide(app):
-    p = os.path.join("docs", f"{app}-UsageGuide.md")
-    roles = []
-    if os.path.isfile(p):
-        m = re.search(r"(?ms)^##\s+(?:\d+[.)]\s*)?Test users[^\n]*\n(.*?)(?=^## |\Z)", read(p))
-        if m:
-            for line in m.group(1).splitlines():
-                c = [x.strip() for x in line.strip().strip("|").split("|")]
-                if len(c) >= 4 and c[0].strip("`* ").isdigit():
-                    roles.append((c[1].strip("`* "), c[3].strip("`* ")))
-    return roles
+    # the guide may be {App}-UsageGuide.md or {App}-Usage-Guide.md, its heading ## or ###, and its
+    # table the template's numbered shape or one read by its header names (AppManager TF-009):
+    # the same reader tf-verify-list.py uses
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("tf_verify_list", os.path.join(os.path.dirname(os.path.abspath(__file__)), "tf-verify-list.py"))
+    vl = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(vl)
+    return [(u["user"], u["role"]) for u in vl.test_users(vl.usage_guide(app))]
 
 
 def screens_from_uidesign(app, phase):
@@ -88,9 +103,9 @@ def screens_from_uidesign(app, phase):
 
 def routes_in_code():
     found = []
-    for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".jsx", ".vue")):
-        if "/" not in f:
-            continue   # a top-level file is never a page
+    for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".jsx", ".vue"), skip_samples=True):
+        if "/" not in f or re.search(r"\.(spec|test)\.\w+$", f):
+            continue   # a top-level file is never a page; a test's `path:` is a screenshot, not a route (TfLens TF-050)
         txt = read(f)
         for ext_re, pat, what in ROUTE_PATTERNS:
             if re.search(ext_re, f, re.I):
@@ -141,7 +156,7 @@ def main(argv):
         kind = argv[argv.index("--kind") + 1].lower()   # override for a project whose config lacks it
     sub = "app"
     if kind.startswith("lib"):
-        razors = [f for f in walk("src", (".razor",), skip_samples=True)] if os.path.isdir("src") else []
+        razors = list(code_files((".razor",)))
         sub = "ui-library" if razors else "service-library"
     print(f"# tf-devguide-list — {app} — kind {sub} — phase {phase}")
     print()
@@ -184,9 +199,9 @@ def main(argv):
             for k in sorted(endpoints):
                 print(f"- {k} — {', '.join(sorted(set(endpoints[k]))[:2])}")
     elif sub == "ui-library":
-        comps = [f for f in walk("src", (".razor",), skip_samples=True)]
+        comps = list(code_files((".razor",)))
         if not comps:
-            print("NOTHING: no component under src/. Build first.")
+            print("NOTHING: no component under src/ or source/. Build first.")
             return 0
         samples = sample_files((".razor", ".cshtml", ".html"))
         stxt = {f: read(f) for f in samples}
@@ -196,9 +211,9 @@ def main(argv):
             shown = [s for s, t in stxt.items() if re.search(rf"<{re.escape(name)}\b", t)]
             print(f"- {os.path.dirname(f).split('/')[-1]} / {name} — {f} — " + (f"shown in {shown[0]}" + (f" (+{len(shown)-1})" if len(shown) > 1 else "") if shown else "NO SAMPLE shows it: a sample gap to log"))
     else:
-        files = [f for f in walk("src", (".cs", ".ts", ".py", ".go", ".java"), skip_samples=True)]
+        files = list(code_files((".cs", ".ts", ".py", ".go", ".java")))
         if not files:
-            print("NOTHING: no source under src/. Build first.")
+            print("NOTHING: no source under src/ or source/. Build first.")
             return 0
         items = []
         for f in files:
@@ -222,6 +237,16 @@ def main(argv):
         print()
         if ver is None:
             print(f"## --update: no existing guide at {gp} (or no \"Verified on\"); everything is new")
+            # a guide kept under another name or folder (Lekhak TF-014: docs/devguides/, one file per
+            # role) is named, so it is read and carried over, never silently rewritten from scratch
+            import glob
+            base = os.path.basename(gp)[:-len(".md")]
+            others = sorted(f for f in glob.glob(os.path.join("docs", "**", base + "*.md"), recursive=True)
+                            if os.path.normpath(f) != os.path.normpath(gp))
+            if others:
+                print(f"- {len(others)} guide file(s) under another name: " + ", ".join(f.replace(os.sep, "/") for f in others[:8])
+                      + (" …" if len(others) > 8 else ""))
+                print(f"  read them and carry every entry that still matches the code into {gp}; do not start from nothing")
         else:
             print(f"## --update: existing guide {gp}, Verified on {ver}, {len(entries)} entries")
             try:
@@ -230,8 +255,8 @@ def main(argv):
             except Exception:
                 cutoff = None
             if cutoff:
-                changed = [f for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".py"), skip_samples=False)
-                           if f.startswith(("src/",)) and os.path.getmtime(f) > cutoff]
+                changed = [f for f in code_files((".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".py"), skip_samples=False)
+                           if os.path.getmtime(f) > cutoff]
                 print(f"- {len(changed)} source file(s) changed since then; remap the entries they serve, keep the rest verbatim")
                 for f in changed[:30]:
                     print(f"  - {f}")

package/.tfcore/utils/tf-doc-check.py

@@ -76,6 +76,7 @@ BRD_RANGE = re.compile(r"(?:BRD-)?(\d+)\s*(?:to|-|–|—)\s*(?:BRD-)?(\d+)", re
 SIZE_NAMES = {"s": "S", "small": "S", "m": "M", "medium": "M", "l": "L", "large": "L"}
 SIZE_LONG = {"S": "Small", "M": "Medium", "L": "Large"}
 REQ_CAP = {"S": 50, "M": 100, "L": 100}
+SCREEN_CAP = {"S": 10, "M": 20, "L": 20}   # Large: per phase
 
 CHECKLIST_HEADER = "| ID | Requirement | Status | % | Remarks | Details |"
 STATUS_VALUES = {
@@ -301,6 +302,12 @@ def detect_kind(path: str):
     name = os.path.basename(path).lower()
     if re.search(r"-deployment-checklist(-[\w]+)?\.md$", name):
         return "deployment-checklist", "app-deployment-checklist-tmpl.md"
+    # phase 2 onward of a Large project: still a BRD to every cross-check, but it carries only
+    # its own screens and requirements and points back at phase 1 for the rest (TF-024)
+    if re.search(r"-p\d+-brd\.md$", name):
+        return "brd", "app-phase-brd-tmpl.md"
+    if re.search(r"-p\d+-uidesign\.md$", name):
+        return "uidesign", "app-phase-uidesign-tmpl.md"
     for suffix, doc, tmpl in DOC_KINDS:
         if name.endswith(suffix):
             return doc, tmpl
@@ -338,6 +345,17 @@ def split_name(path: str):
     return m.group(1), int(m.group(2) or 1)
 
 
+def foreign_prefix(path: str):
+    """The name's app when it is not an app of its folder: docs/AppManager-api-usage-guide.md beside
+    docs/AppManager-BRD.md is an API reference, not a UsageGuide (AppManager TF-024). A folder
+    holding no BRD or checklist anchors nothing, so a lone document is checked by its name."""
+    app, _ = split_name(path)
+    folder = os.path.dirname(os.path.abspath(path))
+    apps = {m.group(1).lower() for m in (re.match(r"(.+?)-(BRD|Checklist)\.md$", f, re.I) for f in os.listdir(folder))
+            if m and not re.search(r"-P\d+$|-Deployment$", m.group(1), re.I)}
+    return app if app and apps and app.lower() not in apps else None
+
+
 def phase_file(app: str, phase: int, suffix: str) -> str:
     return f"{app}-{suffix}.md" if phase <= 1 else f"{app}-P{phase}-{suffix}.md"
 
@@ -386,6 +404,10 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     if not doc:
         rep.warn(path, "not a TechieFlow document name; skipped")
         return None
+    foreign = foreign_prefix(path)
+    if foreign:
+        rep.warn(os.path.relpath(path, root or find_root(path)), f'"{foreign}" is not an app here (no {foreign}-BRD.md or -Checklist.md beside it); not a TechieFlow document, skipped')
+        return None
     try:
         schema = load_schema(tmpl)
     except (OSError, ValueError) as e:
@@ -471,10 +493,18 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     total = word_count(body)
     if size in schema.budget:
         target, mx = schema.budget[size]
+        # The budget holds the size's screen cap of entries. Each entry past it brings its own
+        # per-entry target and maximum, which already bound it (AppManager TF-023: 54 screens).
+        extra, why = 0, ""
+        if schema.entries and schema.per_entry:
+            sec = section_text(present, schema.entries[0]) or ""
+            extra = max(0, sum(1 for h, _t in split_sections(sec, 3) if h) - SCREEN_CAP[size])
+            target, mx = target + extra * schema.per_entry[0], mx + extra * schema.per_entry[1]
+            why = f", with {extra} entries past the cap of {SCREEN_CAP[size]}" if extra else ""
         if total > mx:
-            rep.fail(rel, f"{total:,} words; the {SIZE_LONG[size]} maximum is {mx:,} (target {target:,}). Shorten prose; never drop a screen, field or requirement to fit")
+            rep.fail(rel, f"{total:,} words; the {SIZE_LONG[size]} maximum is {mx:,} (target {target:,}{why}). Shorten prose; never drop a screen, field or requirement to fit")
         elif total > target:
-            rep.warn(rel, f"{total:,} words; the {SIZE_LONG[size]} target is {target:,} (maximum {mx:,})")
+            rep.warn(rel, f"{total:,} words; the {SIZE_LONG[size]} target is {target:,} (maximum {mx:,}{why})")
     for key, h, txt in present:
         d = schema.declared(key)
         if d and d[2]:
@@ -638,6 +668,22 @@ def check_doc_rule(rule, c, rep):
                 elif n_acc > ACC_TARGET:
                     rep.warn(rel, f"BRD-{cur} acceptance line is {n_acc} words; the target is {ACC_TARGET} (maximum {ACC_MAX})")
 
+    elif rule == "phase-pointer":
+        # a phase BRD leaves scope, users, the whole-app non-functionals, constraints and risks to
+        # phase 1, and a phase UIDesign the design system and the click-through flow; this section is
+        # how a reader finds them, so it must actually lead to the phase-1 document of the same kind
+        txt = section_text(present, "Where the rest lives")
+        if txt is None or not c.get("app"):
+            return
+        want = phase_file(c["app"], 1, PHASED_SUFFIX[c["doc"]])
+        hits = [l for l in re.findall(r"\]\(([^)\s]+)\)", txt)
+                if os.path.basename(l.split("#", 1)[0]).lower() == want.lower()]
+        if not hits:
+            rep.fail(rel, f'the "Where the rest lives" section does not link to the phase-1 document ({want}), '
+                          f'where everything the whole application shares lives')
+        elif not any(resolve(root, path, l) for l in hits):
+            rep.fail(rel, f'the "Where the rest lives" link to {hits[0]} points at a file that does not exist')
+
     elif rule == "mockup-links":
         for l in sorted(links_to(clean, "mockups")):
             if not resolve(root, path, l):
@@ -662,6 +708,7 @@ def check_doc_rule(rule, c, rep):
                         continue
                     names.append(r[sc])
         c["brd_screens"] = names
+        check_named_screens(c, rep)
 
     elif rule == "stack-table":
         txt = section_text(present, "Stack decisions")
@@ -863,6 +910,26 @@ def check_doc_rule(rule, c, rep):
         if not re.search(r"(?i)\bblocking\b|\bnothing is blocked\b", txt):
             rep.fail(rel, 'the Summary must say how many entries are blocking right now, '
                           'or "Nothing is blocked" — it is the first thing the owner reads')
+        # ... and its counts must be the entries' own. TfLens's read "20 entries, 8 open" over 27
+        # entries with 7 fixed upstream, and a TrBlazeUI file "all 28 open, none fixed upstream"
+        # under the library's own reply fixing 24 of them (MISS-TechieFlow-20260911-04).
+        sys.path.insert(0, SELF_DIR)
+        import tf_feedback
+        es = tf_feedback.entries(path)
+        n = {s: [e["id"] for e in es if e["state"] == s] for s in ("open", "fixed", "closed")}
+        truth = (f"{len(es)} entries: {len(n['open'])} open, {len(n['fixed'])} fixed upstream and not yet "
+                 f"re-checked, {len(n['closed'])} closed")
+        head = re.split(r"(?m)^####\s", txt)[0]
+        said_total = re.search(r"(?i)\b(\d+)\s+entries\b", head)
+        said_open = re.search(r"(?i)\b(?:all\s+)?(\d+)\s+(?:filed and\s+)?open\b", head)
+        wrong = ((said_total and int(said_total.group(1)) != len(es))
+                 or (said_open and int(said_open.group(1)) != len(n["open"])))
+        if wrong:
+            rep.fail(rel, f"the Summary's counts are not the entries' — the file holds {truth}; "
+                          f"rewrite it from: bash .tfcore/utils/tf-feedback.sh {os.path.basename(path).split('-')[0]}")
+        elif n["fixed"] and not re.search(r"(?i)fixed upstream|re-?check", head):
+            rep.fail(rel, f"{len(n['fixed'])} entries are fixed upstream and not yet re-checked here "
+                          f"({', '.join(n['fixed'][:5])}{' …' if len(n['fixed']) > 5 else ''}); the Summary must say so")
 
     elif rule == "paste-back-block":
         # `present` is built from the prose-only copy, which drops fenced blocks — and a
@@ -973,7 +1040,11 @@ def check_checklist(c, rep):
         n = len(re.findall(r"\S+", remarks))
         if n > 60:
             rep.fail(rel, f"{rid} Remarks is {n} words; at most 60, current state only (history lives in the telemetry streams)")
-        if NOT_PRESENT.search(remarks) and not NAMES_PATH.search(remarks):
+        # text in backticks is quoted — a test's title or message the verdict script copied — not an agent's
+        # claim about a file; an unclosed span (a Remark cut at its word cap) counts as quoted to its end
+        # (Lekhak TF-012)
+        said = re.sub(r"`[^`]*(?:`|$)", " ", remarks)
+        if NOT_PRESENT.search(said) and not NAMES_PATH.search(remarks):
             rep.fail(rel, f"{rid} Remarks says something is not present without naming the path that was tried; search tools skip .tfcore/, so read the literal path first")
         m = re.search(r"\(#([^)]+)\)", details)
         if not m:
@@ -996,8 +1067,15 @@ def check_checklist(c, rep):
         if not m:
             continue  # reported above through the Details link
         pos = m.start()
-        nxt = re.search(r"\n\s*(?:[-*]\s*)?<a id=|\n## |\n### ", body[pos + 1:])   # an entry is a list item: the dash precedes the anchor (miss 21)
-        entry = body[pos: pos + 1 + nxt.start()] if nxt else body[pos:]
+        # A "### Page: …" heading written straight under the entry's own anchor belongs to the entry.
+        # Stopping at the first "### " cut such an entry off before its content: three false failures
+        # each, and 24 AppManager entries never really checked (TF-002). The next one still ends it.
+        start = pos + 1
+        own = re.match(r"<a id=[^>]*>\s*</a>[^\n]*\n(?:[ \t]*\n)*[ \t]*### [^\n]*", body[pos:])
+        if own:
+            start = pos + own.end()
+        nxt = re.search(r"\n\s*(?:[-*]\s*)?<a id=|\n## |\n### ", body[start:])   # an entry is a list item: the dash precedes the anchor (miss 21)
+        entry = body[pos: start + nxt.start()] if nxt else body[pos:]
         acc = [l for l in entry.splitlines() if ACCEPT_LINE.search(l)]
         if len(acc) != 1:
             rep.fail(rel, f"{rid} must have exactly one acceptance line; found {len(acc)}")
@@ -1039,6 +1117,48 @@ def _screen_key(s):
     return re.sub(r"\s+", " ", s).strip().lower()
 
 
+# A requirement names its screen in the template's "*Screen:* <name>" field, or in running text as
+# "**<name>** screen". Either must have a row in some phase's Screens and flow table: the row is what
+# brings the UI design entry and the mockup after it (TF-030).
+SCREEN_FIELD = re.compile(r"\*{1,2}Screen:?\*{1,2}:?\s*([^·*|\n]+)")
+SCREEN_BOLD = re.compile(r"\*\*([^*\n]{2,60})\*\*[ -]screens?\b", re.I)
+NOT_A_NAME = {"every", "any", "each", "one", "this", "that", "the", "a", "new", "same", "other", "whole", "single", "no"}
+
+
+def _table_screen_keys(txt):
+    """Every name in the Screen column of a Screens and flow section, dialogs included."""
+    out = set()
+    for header, rows in tables_in(txt or ""):
+        low = [h.lower() for h in header]
+        if "screen" in low and "route" in low:
+            sc = low.index("screen")
+            out |= {_screen_key(r[sc]) for r in rows if len(r) > sc and r[sc] and not r[sc].startswith("{")}
+    return out
+
+
+def check_named_screens(c, rep):
+    known = _table_screen_keys(section_text(c["present"], "Screens and flow"))
+    if c.get("app"):    # a phase BRD may name a screen another phase's BRD owns
+        for f in sorted(os.listdir(os.path.dirname(c["path"]))):
+            if f != os.path.basename(c["path"]) and re.match(rf"^{re.escape(c['app'])}-(P\d+-)?BRD\.md$", f):
+                with open(os.path.join(os.path.dirname(c["path"]), f), encoding="utf-8") as fh:
+                    other = [(norm_heading(h), h, t) for h, t in split_sections(strip_noise(fh.read()), 2) if h is not None]
+                known |= _table_screen_keys(section_text(other, "Screens and flow"))
+    cur, told = None, set()
+    for line in (section_text(c["present"], "Requirements") or "").splitlines():
+        m = re.search(r"\*\*BRD-(\d+)\*\*", line)
+        if m:
+            cur = m.group(1)
+        for name in [x.group(1) for x in SCREEN_FIELD.finditer(line)] + [x.group(1) for x in SCREEN_BOLD.finditer(line)]:
+            key = _screen_key(name)
+            if not key or name.strip().startswith("{") or key in NOT_A_NAME or key in known or key in told:
+                continue
+            told.add(key)
+            where = f"BRD-{cur}" if cur else "a requirement"
+            rep.fail(c["rel"], f'{where} names the screen "{name.strip()}", which has no row in any Screens and flow table; '
+                               f'add the row, then its UI design entry and its mockup, before it is built')
+
+
 def cross_checks(ctxs: dict, rep: Report, root: str):
     """ctxs is keyed by (doc, phase). Single documents sit at phase 1."""
     phases = sorted({p for (_d, p) in ctxs})
@@ -1092,9 +1212,19 @@ def cross_phase_checks(ctxs, rep, root, phases):
                 rep.fail(cls[p]["rel"], f"{i} is also in phase {seen[i]}'s checklist; REQ ids run on across phases and are never reused")
             seen.setdefault(i, p)
 
+    if not ph and app:
+        # It may simply not have been named on the command line. Read it from disk for this rule and
+        # throw its own findings away, since they belong to a run that names it: saying "the Phases
+        # document does not exist" about a file that is there invites writing over it (TF-041).
+        disk = os.path.join(root, "docs", f"{app}-Phases.md")
+        if os.path.isfile(disk):
+            try:
+                ph = check_document(disk, Report(False), None, root)
+            except Exception:
+                ph = None
     if not ph:
         if len(phases) > 1 and app:
-            rep.fail(f"docs/{app}-Phases.md", f"phase files exist ({', '.join(f'P{p}' for p in phases if p > 1)}) but the Phases document does not; write it from app-phases-tmpl.md")
+            rep.fail(f"docs/{app}-Phases.md", f"phase files exist ({', '.join(f'P{p}' for p in phases if p > 1)}) but no Phases document is on disk; write it from app-phases-tmpl.md")
         return
     rows = ph.get("phases") or []
     if not rows:

package/.tfcore/utils/tf-doc-tests.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# tf-doc-tests.sh — run the unit tests when a test reads a document this command changed (Lekhak TF-016, 2026-09-30).
+#
+#   bash .tfcore/utils/tf-doc-tests.sh <doc> [<doc>…] [--target <sln|csproj>]
+#
+# A project may guard a document with a unit test: Lekhak's VerificationRuleDocTests reads
+# docs/Lekhak-UsageGuide.md and fails when the REQ-NFR-042 paragraph is gone. *amend-docs removed that
+# paragraph, ran no test, closed green, and only CI noticed. This script looks for test source files
+# (a path containing "test") that name one of the documents, by file name or by name without ".md".
+# When one does, it runs the unit tests through tf-build.sh test. Prints ONE line:
+#   NONE     no test reads <docs>; nothing to run                             exit 0
+#   PASS     <n> test file(s) read <docs> (<files>); the unit tests pass — <build line>   exit 0
+#   FAIL     <n> test file(s) read <docs> (<files>); the unit tests fail — <build line>   exit 1
+#   NOT-RUN  the tests could not be run — <reason>                                         exit 2
+# A FAIL means the phase is not closed: a test guards text this command changed.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/tf-portable.sh"   # tf_read_lines, for bash 3.2 on a stock Mac
+DOCS=(); TARGET=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target) TARGET="${2:-}"; shift 2 ;;
+    -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) DOCS+=("$1"); shift ;;
+  esac
+done
+[[ ${#DOCS[@]} -gt 0 ]] || { echo "tf-doc-tests: name at least one document" >&2; exit 2; }
+
+READERS="$(python3 - "${DOCS[@]}" <<'PY'
+import os, sys
+names = set()
+for d in sys.argv[1:]:
+    b = os.path.basename(d)
+    names.add(b)
+    stem = os.path.splitext(b)[0]
+    if len(stem) >= 6:          # "README" alone would match half the code; a real document name is longer
+        names.add(stem)
+EXT = (".cs", ".fs", ".vb", ".ts", ".tsx", ".js", ".mjs", ".py", ".java", ".kt", ".go", ".rs", ".rb", ".swift", ".dart", ".php")
+SKIP = {"node_modules", "bin", "obj", ".git", ".tfcore", ".claude", ".opencode", "docs", ".artifacts"}
+hits = []
+for root, dirs, files in os.walk("."):
+    dirs[:] = [x for x in dirs if x not in SKIP and not (x.startswith(".") and x != ".")]
+    for fn in files:
+        p = os.path.join(root, fn)[2:]
+        if not fn.endswith(EXT) or "test" not in p.lower():
+            continue
+        try:
+            t = open(p, encoding="utf-8", errors="replace").read()
+        except OSError:
+            continue
+        if any(n in t for n in names):
+            hits.append(p)
+print("\n".join(sorted(hits)))
+PY
+)"
+if [[ -z "$READERS" ]]; then
+  echo "NONE     no test reads ${DOCS[*]}; nothing to run"
+  exit 0
+fi
+N="$(wc -l <<<"$READERS" | tr -d ' ')"; LIST="$(tr '\n' ',' <<<"$READERS" | sed 's/,$//; s/,/, /g')"
+
+# the same target choice as tf-verify-tests.sh: a root solution, else the only test project under tests/
+ROOTSLN="$(compgen -G '*.sln'; compgen -G '*.slnx'; compgen -G '*.csproj')"
+tf_read_lines TESTPROJ < <(find tests -name '*.csproj' -not -path 'tests/.artifacts/*' -not -path '*/bin/*' -not -path '*/obj/*' -not -path '*/node_modules/*' 2>/dev/null | sort)
+[[ -z "$TARGET" && -z "$ROOTSLN" && ${#TESTPROJ[@]} -eq 1 ]] && TARGET="${TESTPROJ[0]}"
+if [[ -z "$TARGET" && -z "$ROOTSLN" ]]; then
+  if [[ ${#TESTPROJ[@]} -gt 1 ]]; then
+    echo "NOT-RUN  $N test file(s) read ${DOCS[*]} ($LIST), but there is no solution here and ${#TESTPROJ[@]} test projects; name one with --target"
+  else
+    echo "NOT-RUN  $N test file(s) read ${DOCS[*]} ($LIST), but no .NET solution or test project is here; run the project's own unit tests and report them"
+  fi
+  exit 2
+fi
+LINE="$(bash "$HERE/tf-build.sh" test ${TARGET:+"$TARGET"} 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+case "$LINE" in
+  PASS*)    echo "PASS     $N test file(s) read ${DOCS[*]} ($LIST); the unit tests pass — $LINE"; exit 0 ;;
+  FAIL*)    echo "FAIL     $N test file(s) read ${DOCS[*]} ($LIST); the unit tests fail — $LINE"; exit 1 ;;
+  *)        echo "NOT-RUN  the unit tests could not be run — ${LINE:-tf-build.sh printed no verdict}"; exit 2 ;;
+esac