@techierathore/techieflow 1.0.3 → 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

@@ -52,12 +52,20 @@ DOC_KINDS = [
     ("-devguide.md", "devguide", "app-devguide-tmpl.md"),
     ("-productguide.md", "productguide", "app-productguide-tmpl.md"),
     ("-phases.md", "phases", "app-phases-tmpl.md"),
+    ("-brief.md", "brief", "app-brief-tmpl.md"),
+    ("-decision-request.md", "decision-request", "app-decision-request-tmpl.md"),
+    ("-feedback.md", "feedback", "app-library-feedback-tmpl.md"),
 ]
 SIZED_DOCS = {"brd", "architecture", "uidesign", "checklist", "usageguide", "devguide", "productguide"}
 # Large projects: these four split by phase. Phase 1 keeps the plain name (App-BRD.md);
 # phase 2 onward are App-P2-BRD.md and so on. docs/TechieFlow-Document-Schemas.md §2.
 PHASED_DOCS = {"brd", "checklist", "uidesign", "devguide"}
 PHASED_SUFFIX = {"brd": "BRD", "checklist": "Checklist", "uidesign": "UIDesign", "devguide": "DevGuide"}
+# A feedback entry's heading opens with its id: TF-016, TR-010, TR-RAG-002.
+ENTRY_ID = re.compile(r"^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+\b")
+# A closed entry carries its resolution banner near the top of its body. The banner is not
+# always first: an entry may open with a renumbering or scope note, so the window is generous.
+FEEDBACK_CLOSED = re.compile(r"(?i)(✅|\bfixed upstream\b|\bwill not fix\b|\bwont-fix\b|is \*\*closed\*\*)")
 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)
@@ -68,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 = {
@@ -293,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
@@ -330,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"
 
@@ -378,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:
@@ -429,6 +459,9 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
             continue
         if doc == "checklist" and re.search(r"<a id=['\"]d-req-", txt, re.I):
             continue  # a page group holding detail entries
+        if doc == "feedback" and ENTRY_ID.match(h.strip()):
+            continue  # an entry written at ## level: the layout every feedback file shipped
+                      # with before this schema existed. Read as an entry, not a stranger.
         extra = "; bugs and feedback go to the misses stream, not the checklist" if doc == "checklist" else ""
         rep.fail(rel, f'section "{h}" is not in the template{extra}')
 
@@ -438,6 +471,9 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
         d = schema.declared(key)
         if not d:
             continue
+        if doc == "feedback" and d[1] != "required":
+            continue    # correspondence blocks are appended over time and sit either side
+                        # of the entries; where they land carries no meaning
         idx = order_of[norm_heading(d[0])]
         if idx < last_idx:
             rep.fail(rel, f'section "{h}" comes after "{last_name}"; the template order is the other way round')
@@ -457,14 +493,24 @@ 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]:
-            n = word_count(txt)
+            # A `####` block inside a section is detail the reader chooses to open, and is not
+            # counted — the same rule as a feedback entry's `#### Detail` (owner, 2026-09-08).
+            n = word_count(re.split(r"(?m)^####\s", txt)[0])
             if n > d[2]:
                 rep.fail(rel, f'section "{h}" is {n} words; at most {d[2]}')
     if schema.max_lines:
@@ -479,8 +525,14 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     if schema.entries:
         sec_txt = section_text(present, schema.entries[0])
         prefix = schema.entries[1]
+        pairs = list(split_sections(sec_txt, 3)) if sec_txt is not None else []
+        if doc == "feedback":
+            # Entries may sit under "Entries" as ###, or stand at ## level as every
+            # feedback file wrote them before this schema. Both are read the same way.
+            pairs += [(h, t) for _k, h, t in present if ENTRY_ID.match(h.strip())]
+            sec_txt = sec_txt if sec_txt is not None else ""
         if sec_txt is not None:
-            for h3, etxt in split_sections(sec_txt, 3):
+            for h3, etxt in pairs:
                 if h3 is None:
                     continue
                 if prefix and not h3.lower().startswith(prefix.lower()):
@@ -489,8 +541,16 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
                 ename = h3[len(prefix):].strip() if prefix else h3
                 ename = re.sub(r"\s*\(.*$", "", ename).strip("` ").strip()
                 entry_names.append(ename)
+                if doc == "feedback" and FEEDBACK_CLOSED.search(etxt[:2500]):
+                    continue    # a closed entry is the record of what was wrong and why.
+                                # History may be as long as it needs to be; the shape and the
+                                # word cap bind the LIVE ones, which are what the owner reads.
                 if schema.per_entry:
-                    n = word_count(etxt)
+                    # The cap binds the REPORT, not the working-out. Anything under a `####`
+                    # heading inside the entry is detail a reader chooses to open, and is not
+                    # counted: a thorough analysis is worth having, an entry the owner cannot
+                    # read at a glance is not (owner, 2026-09-08).
+                    n = word_count(re.split(r"(?m)^####\s", etxt)[0])
                     if n > schema.per_entry[1]:
                         rep.fail(rel, f'entry "{ename}" is {n} words; maximum {schema.per_entry[1]} (target {schema.per_entry[0]})')
                     elif n > schema.per_entry[0]:
@@ -549,6 +609,29 @@ def check_entry_rule(rule, ename, etxt, rel, root, path, rep):
     elif rule == "entry-expected":
         if not re.search(r"(?im)^\s*[-*]?\s*\**expected", etxt):
             rep.fail(rel, f'entry "{ename}" has no "Expected:" line')
+    elif rule == "entry-feedback-fields":
+        # A feedback entry is a bug report, not an essay. Same eight fields every time,
+        # so the upstream team reads them in one shape and the owner reads "Blocks" first.
+        for field in ("Severity", "Blocks", "Repro", "Expected", "Actual",
+                      "Encountered in", "Workaround", "Suggested fix"):
+            if not re.search(r"(?im)^\s*[-*]?\s*\**%s\**\s*:" % re.escape(field), etxt):
+                rep.fail(rel, f'entry "{ename}" has no "{field}:" line')
+    elif rule == "entry-blocks-line":
+        # The one word that decides whether the run stops. "no" also has to say what was
+        # done instead, because a non-blocking entry is filed and the work carries on.
+        m = re.search(r"(?im)^\s*[-*]?\s*\**Blocks\**\s*:\s*(.+)$", etxt)
+        if m:
+            val = m.group(1).strip().strip("*` ").lower()
+            if not re.match(r"^(yes|no)\b", val):
+                rep.fail(rel, f'entry "{ename}" says "Blocks: {m.group(1).strip()[:40]}"; it must start "yes" or "no"')
+            elif val.startswith("no") and len(val) < 8:
+                rep.fail(rel, f'entry "{ename}" says "Blocks: no" and stops; say what was done instead and that the work carried on')
+    elif rule == "entry-decision-options":
+        if not has_table_with(etxt, "option", "what happens"):
+            rep.fail(rel, f'decision "{ename}" has no options table (Option, What happens, What it costs)')
+    elif rule == "entry-recommendation":
+        if not re.search(r"(?im)^\s*\**My recommendation", etxt):
+            rep.fail(rel, f'decision "{ename}" has no "My recommendation:" line — the owner is owed one, with the reason in a sentence')
 
 
 def check_doc_rule(rule, c, rep):
@@ -585,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):
@@ -609,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")
@@ -782,6 +882,70 @@ def check_doc_rule(rule, c, rep):
         if re.search(r"\b(and|or)\b|,|/", tgt):
             rep.fail(rel, f'Hosting target "{tgt}" names more than one target; one document per hosting target')
 
+    elif rule == "brief-must-do":
+        txt = section_text(present, "Must do")
+        if txt is None:
+            return
+        n = len(re.findall(r"(?m)^\s*\d+[.)]\s+\S", txt))
+        if n == 0:
+            rep.fail(rel, 'the "Must do" section is not a numbered list; day-1 turns each line into requirements, so one line is one thing the product does')
+        elif n > 25:
+            rep.fail(rel, f'the "Must do" section has {n} lines; a brief that long is a BRD. Keep the page, and let day-1 expand it')
+
+    elif rule == "no-glossary":
+        # A document written for the owner explains itself in plain words or it is
+        # written wrong. A section that defines the document's own vocabulary before it
+        # can ask its question is the tell: the fix is to change the words, never to
+        # teach them (owner, 2026-09-08).
+        for _key, h, _txt in present:
+            if re.search(r"(?i)\b(glossary|terminology|words this document uses|"
+                         r"terms? (used|you)|what these words mean|definitions)\b", h):
+                rep.fail(rel, f'section "{h}" defines this document\'s own vocabulary; '
+                              f'write it in plain English instead — if a word needs a glossary, use a different word')
+
+    elif rule == "feedback-blocking-count":
+        txt = section_text(present, "Summary")
+        if txt is None:
+            return
+        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
+        # fenced block is exactly what this rule looks for. Re-split the uncommented source.
+        raw_present = [(norm_heading(h), h, t) for h, t in split_sections(nocomment, 2) if h is not None]
+        txt = section_text(raw_present, "Copy this back to me")
+        if txt is None:
+            return
+        blocks = re.findall(r"^```", txt, re.M)
+        if len(blocks) < 2:
+            rep.fail(rel, 'the "Copy this back to me" section has no fenced block; '
+                          'the owner answers by pasting it, so it must be there to paste')
+        n_dec = len(c.get("entry_names") or [])
+        if n_dec and len(blocks) // 2 < n_dec:
+            rep.fail(rel, f'{n_dec} decisions but {len(blocks) // 2} paste-back block(s); one per decision')
+
     elif rule == "phases-table":
         txt = section_text(present, "Phases")
         if txt is None:
@@ -876,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:
@@ -899,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)}")
@@ -942,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})
@@ -995,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:
@@ -1148,7 +1375,7 @@ def check_mockups(root: str, rep: Report):
 # ----------------------------------------------------------------------------
 def app_files(root: str, app: str):
     docs = os.path.join(root, "docs")
-    names = [f"{app}-Phases.md", f"{app}-BRD.md", f"{app}-Architecture.md", f"{app}-UIDesign.md", f"{app}-Checklist.md",
+    names = [f"{app}-Brief.md", f"{app}-Phases.md", f"{app}-BRD.md", f"{app}-Architecture.md", f"{app}-UIDesign.md", f"{app}-Checklist.md",
              f"{app}-Coding-Standards.md", f"{app}-UsageGuide.md", f"{app}-DevGuide.md", f"{app}-ProductGuide.md"]
     # later phases of a Large project: App-P2-BRD.md, App-P2-Checklist.md, … in phase order
     extra = []
@@ -1160,6 +1387,11 @@ def app_files(root: str, app: str):
     names += [f for _p, _o, f in sorted(extra)]
     if os.path.isdir(docs):
         names += sorted(f for f in os.listdir(docs) if re.match(rf"^{re.escape(app)}-Deployment-Checklist(-[\w]+)?\.md$", f))
+        # the two documents written for a reader outside this project: the owner's open
+        # decisions, and whatever this project has reported upstream (one file per upstream)
+        names += sorted(f for f in os.listdir(docs)
+                        if re.match(rf"^{re.escape(app)}-Decision-Request\.md$", f)
+                        or re.match(rf"^{re.escape(app)}-[\w.]+-Feedback\.md$", f))
     out = [os.path.join(docs, n) for n in names if os.path.exists(os.path.join(docs, n))]
     ps = os.path.join(root, "PROJECT-STATUS.md")
     if os.path.exists(ps):

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