@techierathore/techieflow 1.0.4 → 1.1.1

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

@@ -70,12 +70,15 @@ DOC_NAME = re.compile(
     r"^(.+?)(?:-P(\d+))?-(BRD|Deployment-Checklist(?:-[\w]+)?|Checklist|UIDesign|DevGuide|Architecture|Coding-Standards|UsageGuide|Usage-Guide|ProductGuide|Phases)\.md$",
     re.I)
 PHASE_FORM = re.compile(r"^(\d+)\s+of\s+(\d+)$", re.I)
-PHASE_STATUS = {"planned", "building", "done"}
+# kept-whole: a phase finished before the size cap that the owner chose to keep as one document;
+# its cap and word maximum are reported as WARN, not FAIL (Lekhak TF-029)
+PHASE_STATUS = {"planned", "building", "done", "kept-whole"}
 BRD_RANGE = re.compile(r"(?:BRD-)?(\d+)\s*(?:to|-|–|—)\s*(?:BRD-)?(\d+)", re.I)
 
 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 = {
@@ -95,9 +98,10 @@ NAMES_SCREEN = re.compile(r"\b(on|opens?|from|in)\b", re.I)
 
 
 def acceptance_words(line: str) -> int:
-    """Words in an acceptance line, without the "Acceptance:" label and without a perf-budget tail."""
+    """Words in an acceptance line, without the "Acceptance:" label and without a perf-budget or
+    zoom-check tail (the markers the verifier reads)."""
     t = re.sub(r"^\s*[-*]\s*\*?Acceptance:?\*?:?\s*", "", line)
-    t = re.split(r"perf-budget:", t, flags=re.I)[0]
+    t = re.split(r"perf-budget:|zoom-check:", t, flags=re.I)[0]
     return len(re.findall(r"\S+", t))
 
 
@@ -301,6 +305,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
@@ -324,7 +334,7 @@ def read_core_config(root: str) -> dict:
     if os.path.exists(p):
         with open(p, encoding="utf-8") as fh:
             for line in fh:
-                m = re.match(r"^(appSize|appKind|appPhase):\s*(\S+)", line)
+                m = re.match(r"^(appSize|appKind|appPhase):\s*(\S+)", line) or re.match(r"^\s+(project_type):\s*(\S+)", line)
                 if m and m.group(2) not in ("null", "~", "''", '""'):
                     out[m.group(1)] = m.group(2).strip("'\"")
     return out
@@ -338,6 +348,35 @@ 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_status(path: str, app: str, phase: int):
+    """The Status cell of this phase's row in docs/{App}-Phases.md beside it, lower-cased; None when
+    there is no Phases document or no row for the phase."""
+    p = os.path.join(os.path.dirname(path), f"{app}-Phases.md")
+    if not app or not os.path.isfile(p):
+        return None
+    with open(p, encoding="utf-8") as fh:
+        txt = strip_noise(fh.read())
+    for header, rows in tables_in(txt):
+        low = [h.lower() for h in header]
+        if "phase" in low and "status" in low:
+            ip, ist = low.index("phase"), low.index("status")
+            for r in rows:
+                if len(r) > max(ip, ist) and r[ip].strip("`* ") == str(phase):
+                    return r[ist].strip("`* ").lower()
+    return 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 +425,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:
@@ -428,6 +471,10 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
             rep.fail(rel, f'a phase-{phase} file needs the header row "Phase | {phase} of <m>"')
         elif os.path.exists(phases_doc):
             rep.fail(rel, f'the project has phases ({os.path.relpath(phases_doc, root)}); this file needs the header row "Phase | 1 of <m>"')
+    # a phase the owner kept whole past the cap: its size findings are WARN, never a gate failure (Lekhak TF-029)
+    kept = doc in PHASED_DOCS and bool(app) and phase_status(path, app, phase) == "kept-whole"
+    size_finding = rep.warn if kept else rep.fail
+    kept_why = f"; phase {phase} is kept-whole in {app}-Phases.md, so this is reported, not blocking" if kept else ""
 
     # 2. sections: strangers, order, presence
     present = [(norm_heading(h), h, txt) for h, txt in split_sections(clean, 2) if h is not None]
@@ -471,10 +518,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")
+            size_finding(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{kept_why}")
         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]:
@@ -534,7 +589,7 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     # 5. document rules
     ctx = dict(doc=doc, body=body, clean=clean, nocomment=nocomment, present=present, header=header,
                size=size, kind=kind, root=root, path=path, rel=rel, entry_names=entry_names,
-               app=app, phase=phase)
+               app=app, phase=phase, size_finding=size_finding, kept_why=kept_why)
     for rule in schema.rules:
         if not rule.startswith("entry-"):
             check_doc_rule(rule, ctx, rep)
@@ -623,7 +678,7 @@ def check_doc_rule(rule, c, rep):
         if dupes:
             rep.fail(rel, "duplicate requirement ids: " + ", ".join(f"BRD-{d}" for d in sorted(dupes, key=int)))
         if len(seen) > REQ_CAP[size]:
-            rep.fail(rel, f"{len(seen)} requirements; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases (each phase its own BRD) instead of growing this one")
+            c["size_finding"](rel, f"{len(seen)} requirements; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases (each phase its own BRD) instead of growing this one{c['kept_why']}")
         c["brd_ids"] = seen
         req = section_text(present, "Requirements") or ""
         cur = None
@@ -638,6 +693,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 +733,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 +935,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
@@ -919,7 +1011,7 @@ def check_doc_rule(rule, c, rep):
                             rep.fail(rel, f"phase {n} BRD range runs backwards ({x} to {y})")
                 st = r[ist].strip("`* ").lower()
                 if st not in PHASE_STATUS:
-                    rep.fail(rel, f'phase {n} status "{r[ist]}" must be planned, building or done')
+                    rep.fail(rel, f'phase {n} status "{r[ist]}" must be planned, building, done or kept-whole')
                 rows_out.append(dict(n=n, name=r[iname].strip("`* "), screens=screens, lo=lo, hi=hi, ranges=ranges, status=st))
         nums = [p["n"] for p in rows_out]
         if nums != list(range(1, len(nums) + 1)):
@@ -966,15 +1058,25 @@ def check_checklist(c, rep):
         row_status[rid] = status.strip("`* ").lower()
         if not re.fullmatch(r"REQ-(UI|FN|RAG|NFR)-\d{3}", rid):
             rep.fail(rel, f'id "{rid}" is not REQ-UI/FN/RAG/NFR- plus three digits')
+        removed = " A removed row reads N/A with % 0, and the date goes in Remarks"
         if status.strip("`* ").lower() not in STATUS_VALUES:
-            rep.fail(rel, f'{rid} status "{status}" is not one of the fixed values')
+            rep.fail(rel, f'{rid} status "{status}" is not one of the fixed values.'
+                          + (removed if status.strip("`* ").lower().startswith("n/a") else ""))
         if pct.strip("`* ").rstrip("%").strip() not in ("0", "25", "50", "75", "100"):
-            rep.fail(rel, f'{rid} % "{pct}" must be 0, 25, 50, 75 or 100')
+            rep.fail(rel, f'{rid} % "{pct}" must be 0, 25, 50, 75 or 100.' + removed)
         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")
+        if row_status[rid] == "n/a":
+            # a removed or reserved row is kept for traceability; it has no screen, mockup or BRD item to
+            # point at, so the detail-entry rules do not apply to it (Lekhak TF-028)
+            continue
         m = re.search(r"\(#([^)]+)\)", details)
         if not m:
             rep.fail(rel, f"{rid} Details cell has no link to its detail entry")
@@ -983,7 +1085,7 @@ def check_checklist(c, rep):
     if not ids:
         rep.fail(rel, "the Requirements Status table has no REQ- rows")
     if len(ids) > REQ_CAP[size]:
-        rep.fail(rel, f"{len(ids)} rows; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases instead of growing this checklist")
+        c["size_finding"](rel, f"{len(ids)} rows; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases instead of growing this checklist{c['kept_why']}")
     dupes = sorted({i for i in ids if ids.count(i) > 1})
     if dupes:
         rep.fail(rel, "duplicate rows: " + ", ".join(dupes))
@@ -996,8 +1098,18 @@ 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:]
+        if row_status.get(rid) == "n/a":
+            brd_refs.update(re.findall(r"BRD-(\d+)", entry))   # a retired BRD item still has its row
+            continue
         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)}")
@@ -1022,7 +1134,10 @@ def check_checklist(c, rep):
         brd_refs.update(refs)
         if rid.startswith("REQ-UI"):
             links = links_to(entry, "mockups")
-            if not links:
+            # a library or docs project (metrics.project_type, or kind: library) has no screens and no
+            # docs/mockups/: its UI rows map to components, so a missing link is not a finding there; a
+            # link it does carry must still resolve (TrBlazeUI TF-003)
+            if not links and c.get("kind") == "app" and read_core_config(root).get("project_type", "app").lower() not in ("library", "docs"):
                 rep.fail(rel, f"{rid} is a UI row without a mockup link")
             for l in sorted(links):
                 if not resolve(root, path, l):
@@ -1039,6 +1154,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 +1249,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:
@@ -1145,14 +1312,18 @@ NAV_ITEM = re.compile(r"""<(div|li|span|button)\b[^>]*\bclass\s*=\s*["'][^"']*(?
 
 
 def _mock_target(mock_dir: str, t: str):
-    """Resolve a link the way a browser opening docs/mockups/<file> would. Returns the file
-    name when it lands on an existing file inside the mockup folder, else None."""
+    """Resolve a link the way a browser opening docs/mockups/<file> would. Returns the path
+    relative to the mockup folder when it lands on an existing file inside it, at any depth
+    (Lekhak TF-008: index.html linking to admin/connection-settings.html opens, and was
+    failed), else None. A leading slash, or a path that leaves docs/mockups/, is still None."""
     if re.match(r"^(https?:|mailto:|tel:|javascript:|data:)", t, re.I) or t.startswith("/"):
         return None
+    t = re.split(r"[?#]", t, maxsplit=1)[0]
+    base = os.path.normpath(mock_dir)
     p = os.path.normpath(os.path.join(mock_dir, t))
-    if os.path.dirname(p) != os.path.normpath(mock_dir) or not os.path.isfile(p):
+    if not (p == base or p.startswith(base + os.sep)) or not os.path.isfile(p):
         return None
-    return os.path.basename(p)
+    return os.path.relpath(p, base).replace(os.sep, "/")
 
 
 def check_mockups(root: str, rep: Report):
@@ -1185,7 +1356,8 @@ def check_mockups(root: str, rep: Report):
                 continue
             name = _mock_target(mock_dir, t)
             if name is None:
-                hint = "write the file name alone, not a folder or a leading slash" if ("/" in t) else "the file does not exist"
+                hint = ("a leading slash opens from the disk's root; write the path from docs/mockups/" if t.startswith("/")
+                        else "the file does not exist inside docs/mockups/")
                 rep.fail(rel, f'links to "{t}", which does not open from docs/mockups/ ({hint})')
             else:
                 targets.append(name)
@@ -1290,6 +1462,7 @@ def main(argv=None):
     if a.app:
         root = root or os.getcwd()
         files += app_files(root, a.app)
+        files = list(dict.fromkeys(os.path.abspath(f) for f in files))   # a file given and listed by --app once
         if not files:
             print(f"tf-doc-check: no documents for app {a.app} under {root}", file=sys.stderr)
             return 2
@@ -1322,9 +1495,16 @@ def main(argv=None):
                 base = json.load(fh) or {}
         except Exception:
             base = {}
-        for f in files:
-            r = os.path.relpath(f, root)
-            base[r] = sorted({l.split(": ", 1)[1] for l in rep.lines if l.startswith("FAIL ") and l.split(": ", 1)[0].endswith(" " + r)})
+        # every finding, under whatever it names: the mockup-folder and cross-document checks name
+        # docs/mockups/index.html or another document, not one of the files given, and were never
+        # recorded, so ~60 old findings read as new on every *amend-docs (Lekhak TF-023)
+        new = {os.path.relpath(f, root): set() for f in files}
+        for l in rep.lines:
+            if l.startswith("FAIL ") and ": " in l:
+                head, msg = l.split(": ", 1)
+                new.setdefault(head[len("FAIL "):], set()).add(msg)
+        for r, msgs in new.items():
+            base[r] = sorted(msgs)
         os.makedirs(os.path.dirname(base_path), exist_ok=True)
         with open(base_path, "w", encoding="utf-8") as fh:
             json.dump(base, fh, indent=1)
@@ -1338,11 +1518,23 @@ def main(argv=None):
                 with open(base_path, encoding="utf-8") as fh:
                     base = json.load(fh) or {}
                 relined = []
+                # A size finding carries its count ("20,677 words; the Small maximum is 8,000"), so any
+                # edit to an over-limit document, a cut included, changed the text and read as new
+                # (Lekhak TF-023). The same finding with a count no larger than the old one is old;
+                # a document that grew past its maximum still FAILs.
+                def _shape(m):
+                    return re.sub(r"\d[\d,]*", "#", m)
+                def _first(m):
+                    n = re.search(r"\d[\d,]*", m)
+                    return int(n.group(0).replace(",", "")) if n else None
                 for l in rep.lines:
                     if l.startswith("FAIL "):
                         head, msg = l.split(": ", 1)
                         r = head[len("FAIL "):]
-                        if msg in set(base.get(r, [])):
+                        was = base.get(r, [])
+                        same = msg in set(was) or (re.match(r"^\d[\d,]* (words|lines|rows|requirements|KB|screens)", msg) and any(
+                            _shape(o) == _shape(msg) and _first(o) is not None and _first(msg) <= _first(o) for o in was))
+                        if same:
                             relined.append("OLD  " + l[5:])
                             rep.fails -= 1
                             old += 1

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

@@ -0,0 +1,116 @@
+#!/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 test projects holding those files, each on its own through tf-build.sh
+# test (TechieRag TF-004), or the solution's tests one project at a time. 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,16p' "$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
+# Only the test projects that hold a reader, each on its own (TechieRag TF-004): the whole solution at
+# once let the local-model tests take the memory, and TechieRag.Tests failed with "Cannot allocate
+# memory" on a test that passes alone. A reader in no .NET test project (a browser spec) falls back to
+# the solution run, which tf-build.sh also splits into one test project at a time.
+OWNERS="$(TF_READERS="$READERS" python3 - <<'PY'
+import glob, os, sys
+out = []
+for r in os.environ.get("TF_READERS", "").split("\n"):
+    if not r.strip():
+        continue
+    d = os.path.dirname(r)
+    while d and d not in (".", "/"):
+        projs = glob.glob(os.path.join(d, "*.csproj"))
+        if projs:
+            p = projs[0]
+            if p not in out:
+                out.append(p)
+            break
+        d = os.path.dirname(d)
+print("\n".join(out))
+PY
+)"
+if [[ -n "$OWNERS" && -z "$TARGET" ]]; then
+  fails=(); notrun=(); passed=0; vl=()
+  while IFS= read -r p; do
+    [[ -z "$p" ]] && continue
+    v="$(bash "$HERE/tf-build.sh" test "$p" 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+    vl+=("$(basename "$p" .csproj): ${v:-no verdict}")
+    case "$v" in PASS*) passed=$((passed+1)) ;; FAIL*) fails+=("$(basename "$p" .csproj)") ;; *) notrun+=("$(basename "$p" .csproj)") ;; esac
+  done <<<"$OWNERS"
+  k="$(grep -c . <<<"$OWNERS")"
+  if [[ ${#fails[@]} -gt 0 ]]; then LINE="FAIL  ${fails[*]} failed ($k test project(s) holding a reader, each run on its own) — ${vl[*]}"
+  elif [[ ${#notrun[@]} -gt 0 ]]; then LINE="NOT-RUN ${notrun[*]} could not run — ${vl[*]}"
+  else LINE="PASS  $k test project(s) holding a reader, each run on its own — ${vl[*]}"; fi
+else
+  LINE="$(bash "$HERE/tf-build.sh" test ${TARGET:+"$TARGET"} 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+fi
+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