@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/utils/tf-assets-browser.mjs

@@ -0,0 +1,96 @@
+// TechieFlow — the documents tf-assets.sh grades, fetched through a signed-in browser
+// (AppManager TF-011, 2026-09-14). Driven by tf-assets.sh when --login-path is given; run that.
+//
+// tf-assets reads what a page DECLARES and fetches each asset. It fetched the page with a bare HTTP
+// request, and an app whose sign-in lives in the page's own connection answers 401 to every bare
+// request: "declared 0, graded 0" on every path. Here each path is opened in a browser tab that
+// signed in through the page's form (tf-login.mjs), judged by what it draws, and its document — the
+// head with every stylesheet and script it declares — handed back for grading. The assets themselves
+// are still fetched one by one by tf-assets.sh, so a 404 stays observable.
+//
+//   node tf-assets-browser.mjs --base URL --paths "/a,/b" --login-path /login --user U --password P
+//        [--storage-state file] [--cookie 'k=v'] --json-out <file>
+// Writes {"login": {...}, "pages": {"/a": {"status": 401, "reached": "…", "signed_out": false,
+// "url": "...", "html": "<!doctype…"}}}. Exit 0 always except a usage error (3).
+
+import { chromium } from 'playwright';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { signIn, reach } from './tf-login.mjs';
+
+const argv = process.argv.slice(2);
+const arg = (name, dflt = null) => { const i = argv.indexOf(name); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : dflt; };
+const BASE = (arg('--base') || '').replace(/\/$/, '');
+const PATHS = (arg('--paths', '/') || '').split(',').map((p) => p.trim()).filter(Boolean).map((p) => (p.startsWith('/') ? p : '/' + p));
+const OUT = arg('--json-out');
+const COOKIE = arg('--cookie'); const STORAGE = arg('--storage-state');
+const LOGIN_OPTS = { base: BASE, loginPath: arg('--login-path'), user: arg('--user'), password: arg('--password'), settle: 1500, renderWait: 5000 };
+// Lekhak TF-006: a desktop head, attached over its DevTools port. Its pages and assets are served by
+// the embedded browser itself, so no request from outside can fetch them: each path is opened by
+// pushState, and every asset the document declares is fetched from inside the page, its status and
+// size handed back beside the document ("fetched").
+const CDP = arg('--cdp') || '';
+if ((!BASE && !CDP) || !OUT) { console.error('usage: tf-assets-browser.mjs --base URL|--cdp URL --paths /a,/b [--login-path /login --user U --password P] --json-out file'); process.exit(3); }
+
+if (CDP) {
+  let b, page;
+  try {
+    b = await chromium.connectOverCDP(CDP, { timeout: 15000 });
+    const c = b.contexts()[0]; page = c && c.pages()[0];
+  } catch (e) { page = null; }
+  mkdirSync(dirname(resolve(OUT)), { recursive: true });
+  if (!page) { writeFileSync(resolve(OUT), JSON.stringify({ unreachable: true, cdp: CDP })); process.exit(0); }
+  const pages = {};
+  let origin = '';
+  for (const p of PATHS) {
+    let status = 200, error = '', html = '', url = '', fetched = {};
+    try {
+      await page.evaluate((r) => { history.pushState({}, '', r); window.dispatchEvent(new PopStateEvent('popstate', { state: {} })); }, p);
+      await page.waitForTimeout(LOGIN_OPTS.settle);
+      url = page.url(); origin = origin || new URL(url).origin;
+      html = await page.content();
+      fetched = await page.evaluate(async () => {
+        const out = {};
+        const urls = [...document.querySelectorAll('link[href]')].filter((l) => /stylesheet|preload|modulepreload|icon/i.test(l.rel)).map((l) => l.href)
+          .concat([...document.querySelectorAll('script[src]')].map((s) => s.src));
+        for (const u of [...new Set(urls)]) {
+          if (!/^https?:/i.test(u)) continue;
+          try { const r = await fetch(u, { cache: 'no-store' }); const buf = await r.arrayBuffer(); out[u] = { status: r.status, bytes: buf.byteLength }; }
+          catch (e) { out[u] = { status: null, bytes: 0, error: String(e.message || e).slice(0, 120) }; }
+        }
+        return out;
+      });
+    } catch (e) { status = 0; error = e.message.split('\n')[0]; }
+    pages[p] = { status, document_status: status, url, reached: 'opened inside the attached app (pushState)', signed_out: false, error, html, fetched };
+  }
+  await b.close().catch(() => {});   // disconnects; the app keeps running
+  writeFileSync(resolve(OUT), JSON.stringify({ login: null, cdp: CDP, origin, pages }));
+  process.exit(0);
+}
+
+const browser = await chromium.launch();
+const ctxOpts = { ignoreHTTPSErrors: true };
+if (STORAGE && existsSync(STORAGE)) ctxOpts.storageState = STORAGE;
+const ctx = await browser.newContext(ctxOpts);
+if (COOKIE) {
+  const u = new URL(BASE);
+  for (const pair of COOKIE.split(';')) {
+    const [name, ...v] = pair.trim().split('=');
+    if (name && v.length) await ctx.addCookies([{ name: name.trim(), value: v.join('='), domain: u.hostname, path: '/' }]);
+  }
+}
+const page = await ctx.newPage();
+const login = await signIn(page, LOGIN_OPTS);
+const pages = {};
+for (const p of PATHS) {
+  const nav = await reach(page, LOGIN_OPTS, p);
+  let html = '';
+  if (nav.status && nav.status < 400 && !nav.signedOut) {
+    try { html = await page.content(); } catch (e) { html = ''; }
+  }
+  pages[p] = { status: nav.status, document_status: nav.document_status ?? nav.status, url: nav.url || '',
+               reached: nav.reached || '', signed_out: !!nav.signedOut, error: nav.error || '', html };
+}
+await browser.close();
+mkdirSync(dirname(resolve(OUT)), { recursive: true });
+writeFileSync(resolve(OUT), JSON.stringify({ login, pages }));

package/.tfcore/utils/tf-assets.sh

@@ -3,6 +3,13 @@
 #
 #   bash .tfcore/utils/tf-assets.sh --base http://localhost:5099 \
 #        --paths "/,/login,/export" --cookie 'AuthCookie=<value>'
+#   An app whose sign-in lives in the page and sets no cookie (AppManager TF-011):
+#        --login-path /login --user <u> --password <p>   (or --storage-state <file>)
+#   opens each path in a browser that signed in through the form and grades the
+#   document it drew; `pages[].reached` says how a 401 page was reached.
+#   A desktop head (Lekhak TF-006): --cdp http://<host>:9223 in place of --base attaches to the app,
+#   opens each path by pushState and fetches every declared asset from inside the page, because
+#   nothing outside the embedded browser can reach the files it serves.
 #
 # WHAT IT ASKS, and it is the only question no other gate asks:
 #
@@ -50,8 +57,10 @@
 
 set -uo pipefail
 
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 BASE=""; PATHS="/"; TIMEOUT=20; LABEL=""; OUT=""; EXTERNAL=0; MINBYTES=1
 HDRS=""   # newline-separated "K: V" pairs (--header, repeatable; --cookie is sugar)
+COOKIE=""; LOGIN_PATH=""; USER=""; PASS=""; STORAGE=""; CDP=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --base)             BASE="${2:-}"; shift 2 ;;
@@ -62,18 +71,44 @@ while [[ $# -gt 0 ]]; do
     --min-bytes)        MINBYTES="${2:-}"; shift 2 ;;
     --include-external) EXTERNAL=1; shift ;;
     --header)           HDRS="${HDRS}${2:-}"$'\n'; shift 2 ;;
-    --cookie)           HDRS="${HDRS}Cookie: ${2:-}"$'\n'; shift 2 ;;
-    -h|--help)          sed -n '2,48p' "$0"; exit 0 ;;
+    --cookie)           HDRS="${HDRS}Cookie: ${2:-}"$'\n'; COOKIE="${2:-}"; shift 2 ;;
+    # a sign-in the page keeps for itself sets no cookie (AppManager TF-011): the pages are then
+    # opened in a browser that signed in through the form, the same options tf-verify-screens takes
+    --login-path)       LOGIN_PATH="${2:-}"; shift 2 ;;
+    --user)             USER="${2:-}"; shift 2 ;;
+    --password)         PASS="${2:-}"; shift 2 ;;
+    --storage-state)    STORAGE="${2:-}"; shift 2 ;;
+    --cdp)              CDP="${2:-}"; shift 2 ;;   # a desktop head over its DevTools port (Lekhak TF-006)
+    -h|--help)          sed -n '2,56p' "$0"; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 3 ;;
   esac
 done
 
-[[ -n "$BASE" ]] || { printf '%s\n' \
-  "usage: tf-assets.sh --base URL [--paths /,/login] [--cookie 'k=v'] [--include-external]" \
+[[ -n "$BASE" || -n "$CDP" ]] || { printf '%s\n' \
+  "usage: tf-assets.sh --base URL|--cdp URL [--paths /,/login] [--cookie 'k=v'] [--include-external]" \
+  "                    [--login-path /login --user U --password P] [--storage-state file]" \
   "                    [--json-out tests/.artifacts/assets/REQ-NFR-015.json]" >&2; exit 3; }
 command -v python3 >/dev/null 2>&1 || { echo '{"status":"no-python3"}'; exit 3; }
 
-TF_BASE="$BASE" TF_PATHS="$PATHS" TF_TIMEOUT="$TIMEOUT" TF_LABEL="$LABEL" TF_OUT="$OUT" \
+# ---- the documents, through a signed-in browser when a sign-in is given (TF-011) --------------
+DOCS=""
+if [[ -n "$CDP" ]]; then
+  if ! command -v node >/dev/null 2>&1 || ! node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null; then
+    echo '{"status":"no-playwright","note":"--cdp needs node and playwright (verify-phase §1 installs the verify environment)"}'; exit 3
+  fi
+  DOCS="$(mktemp "${TMPDIR:-/tmp}/tmp.XXXXXXXXXX")" && mv "$DOCS" "$DOCS.json" && DOCS="$DOCS.json"
+  node "$HERE/tf-assets-browser.mjs" --cdp "$CDP" --paths "$PATHS" --json-out "$DOCS" >&2 || { echo '{"status":"browser-failed"}'; rm -f "$DOCS"; exit 3; }
+elif [[ -n "$LOGIN_PATH" || -n "$STORAGE" ]]; then
+  if ! command -v node >/dev/null 2>&1 || ! node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null; then
+    echo '{"status":"no-playwright","note":"--login-path needs node and playwright (verify-phase §1 installs the verify environment)"}'; exit 3
+  fi
+  DOCS="$(mktemp "${TMPDIR:-/tmp}/tmp.XXXXXXXXXX")" && mv "$DOCS" "$DOCS.json" && DOCS="$DOCS.json"   # only GNU mktemp takes a suffix option
+  node "$HERE/tf-assets-browser.mjs" --base "$BASE" --paths "$PATHS" --json-out "$DOCS" \
+       ${LOGIN_PATH:+--login-path "$LOGIN_PATH"} ${USER:+--user "$USER"} ${PASS:+--password "$PASS"} \
+       ${STORAGE:+--storage-state "$STORAGE"} ${COOKIE:+--cookie "$COOKIE"} >&2 || { echo '{"status":"browser-failed"}'; rm -f "$DOCS"; exit 3; }
+fi
+
+TF_CDP="$CDP" TF_BASE="$BASE" TF_PATHS="$PATHS" TF_TIMEOUT="$TIMEOUT" TF_LABEL="$LABEL" TF_OUT="$OUT" TF_DOCS="$DOCS" \
 TF_HEADERS="$HDRS" TF_EXTERNAL="$EXTERNAL" TF_MINBYTES="$MINBYTES" python3 - <<'PY'
 import html.parser, json, os, ssl, sys, urllib.error, urllib.request
 from urllib.parse import urljoin, urlsplit
@@ -85,6 +120,34 @@ LABEL    = os.environ.get("TF_LABEL") or None
 OUT      = os.environ.get("TF_OUT") or None
 EXTERNAL = os.environ.get("TF_EXTERNAL") == "1"
 MINBYTES = int(os.environ.get("TF_MINBYTES") or 1)
+# the documents a signed-in browser fetched, by path (TF-011); empty when none was asked for
+DOCS = {}
+LOGIN = None
+if os.environ.get("TF_DOCS"):
+    try:
+        _d = json.load(open(os.environ["TF_DOCS"], encoding="utf-8"))
+        DOCS, LOGIN = _d.get("pages", {}), _d.get("login")
+    except Exception:
+        DOCS = {}
+    try:
+        os.remove(os.environ["TF_DOCS"])
+    except Exception:
+        pass
+# an attached desktop head (TF-006): the assets were fetched inside the page, by URL
+CDP = os.environ.get("TF_CDP") or ""
+FETCHED = {}
+if CDP:
+    try:
+        _d
+    except NameError:
+        _d = {}
+    if _d.get("unreachable") or not DOCS:
+        print(json.dumps({"status": "unreachable", "base": CDP, "label": LABEL,
+                          "note": "the desktop head's DevTools port did not answer — a `build` gate problem, not an assets result"}, indent=2))
+        raise SystemExit(2)
+    BASE = (_d.get("origin") or "").rstrip("/")
+    for _pg in DOCS.values():
+        FETCHED.update(_pg.get("fetched") or {})
 
 HEADERS = []
 for line in (os.environ.get("TF_HEADERS") or "").splitlines():
@@ -145,6 +208,11 @@ class AssetParser(html.parser.HTMLParser):
 def fetch(url, want_body=True):
     """Return (status, nbytes, error). Never raises — a transport failure is a
     finding, not a crash, and the caller needs every path's result."""
+    if CDP:
+        f = FETCHED.get(url)
+        if f is None:
+            return None, 0, "not fetched inside the attached app", b""
+        return f.get("status"), f.get("bytes", 0), f.get("error"), b""
     req = urllib.request.Request(url, headers={"User-Agent": UA})
     for k, v in HEADERS:
         req.add_header(k, v)
@@ -193,7 +261,7 @@ def fetch_page(url):
 
 
 # --- reachability first: an unreachable base is a `build` problem, not an assets one
-probe_status, _, probe_err = fetch_page(BASE + "/")
+probe_status, _, probe_err = (200, b"", None) if CDP else fetch_page(BASE + "/")
 if probe_status is None:
     print(json.dumps({"status": "unreachable", "base": BASE, "error": probe_err,
                       "label": LABEL, "note": "app not reachable — this is a `build` "
@@ -207,7 +275,23 @@ graded_assets = 0
 
 for p in PATHS:
     page_url = BASE + (p if p.startswith("/") else "/" + p)
-    status, body, err = fetch_page(page_url)
+    extra = {}
+    doc = DOCS.get(p if p.startswith("/") else "/" + p)
+    if doc is not None:
+        # the document as the signed-in browser drew it (TF-011). A page that stayed signed out is
+        # an auth wall: nothing of it is graded, like a redirect to the sign-in page.
+        if doc.get("signed_out"):
+            redirected += 1
+            pages.append({"path": p, "status": doc.get("document_status"), "assets": [], "declared": 0,
+                          "graded": 0, "failed": 0, "redirected": True, "auth_wall": True, "url": doc.get("url")})
+            continue
+        status, body, err = (doc.get("status") or None), (doc.get("html") or "").encode("utf-8"), (doc.get("error") or None)
+        if status and status < 400 and body:
+            status = 200
+        if doc.get("reached"):
+            extra = {"document_status": doc.get("document_status"), "reached": doc["reached"]}
+    else:
+        status, body, err = fetch_page(page_url)
     if status is None:
         pages.append({"path": p, "status": None, "error": err, "assets": [],
                       "declared": 0, "graded": 0, "failed": 0})
@@ -269,16 +353,16 @@ for p in PATHS:
 
     pages.append({"path": p, "status": status, "declared": len(rows),
                   "graded": sum(1 for r in rows if r.get("graded")),
-                  "failed": failed, "assets": rows})
+                  "failed": failed, "assets": rows, **extra})
 
 # Every path turned away = nothing was graded. Reporting "0 findings" there would be
 # a PASS on a screen the harness never saw — the same false green tf-perf.sh's exit 4
 # exists to prevent, and the same shape as TF-011's ungradeable-looks-clean failure.
 if PATHS and redirected == len(PATHS):
-    out = {"status": "redirected", "base": BASE, "label": LABEL, "pages": pages,
-           "findings": [], "note": "every path answered 3xx — nothing was graded. "
-           "Present a session with --cookie / --header and re-run. Grade the REQ "
-           "ASSETS-UNMEASURED (auth wall); never record this as a pass."}
+    out = {"status": "redirected", "base": BASE, "label": LABEL, "pages": pages, "login": LOGIN,
+           "findings": [], "note": "every path answered 3xx or stayed signed out — nothing was graded. "
+           "Present a session with --cookie / --header, or --login-path/--user/--password, and re-run. "
+           "Grade the REQ ASSETS-UNMEASURED (auth wall); never record this as a pass."}
     print(json.dumps(out, indent=2))
     if OUT:
         os.makedirs(os.path.dirname(os.path.abspath(OUT)), exist_ok=True)
@@ -294,6 +378,7 @@ out = {
     "findings_n": len(findings),
     "findings": findings,
     "pages": pages,
+    "login": LOGIN,
     "include_external": EXTERNAL,
     # An assets run that graded nothing is UNGRADEABLE, not clean. Said out loud in
     # the payload so a consumer cannot read `findings_n: 0` as coverage.

package/.tfcore/utils/tf-brd-status.py

@@ -16,8 +16,9 @@ docs/<App>-BRD.md (Screen | Requirements | Verified | Open | Status) with a
 re-renders docs/<App>-BRD.html through tf-render-html.sh unless --no-render.
 
 Status per screen: Done (every row terminal), Planned (no row started),
-Partial (some terminal, some open), In progress (started, none terminal).
-Terminal = Verified, Done (pre-existing), N/A. Blocked is counted as open.
+Partial (some terminal, some open), In progress (started, none terminal), Not applicable
+(every row N/A). Terminal = Verified, Done (pre-existing). An N/A row is left out of the counts,
+never counted as verified (AppManager TF-018). Blocked is counted as open.
 
 Python 3 standard library only. Exit 0 written or nothing to do, 2 could not run.
 """
@@ -27,7 +28,9 @@ import re
 import subprocess
 import sys
 
-TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+# norm() drops a bracketed tail, so "Done (pre-existing)" arrives as "done" and was counted open (AppManager TF-003)
+TERMINAL = {"verified", "done", "done (pre-existing)"}
+NA = {"n/a"}
 NOT_STARTED = {"not started"}
 
 
@@ -80,6 +83,8 @@ def table(rows, screen_of):
         if s not in per:
             per[s] = {"n": 0, "v": 0, "ns": 0}
             order.append(s)
+        if status in NA:
+            continue
         per[s]["n"] += 1
         per[s]["v"] += 1 if status in TERMINAL else 0
         per[s]["ns"] += 1 if status in NOT_STARTED else 0
@@ -87,7 +92,9 @@ def table(rows, screen_of):
     for s in order:
         d = per[s]
         open_n = d["n"] - d["v"]
-        if open_n == 0:
+        if d["n"] == 0:
+            st = "Not applicable"
+        elif open_n == 0:
             st = "Done"
         elif d["ns"] == d["n"]:
             st = "Planned"
@@ -153,7 +160,9 @@ def main(argv):
     with open(brd, "w", encoding="utf-8") as f:
         f.write(new_text)
     verified = sum(1 for _, s in rows if s in TERMINAL)
-    print(f"tf-brd-status: {brd_rel} Development status {how}: {screens} screens, {verified} of {len(rows)} requirements verified")
+    na = sum(1 for _, s in rows if s in NA)
+    print(f"tf-brd-status: {brd_rel} Development status {how}: {screens} screens, {verified} of {len(rows) - na} "
+          f"requirements verified" + (f", {na} not applicable" if na else ""))
     if render:
         script = os.path.join(root, ".tfcore", "utils", "tf-render-html.sh")
         if os.path.isfile(script):

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

@@ -4,11 +4,14 @@
     bash .tfcore/utils/tf-build-list.sh <App> [--phase N] [--prompts]
 
 Reads the phase's checklist (appPhase in core-config.yaml, or --phase) and prints:
-  - the mode: FIX (rows FAIL / PARTIAL / In Progress / Needs re-verify exist), FRESH
-    (every open row), or NOTHING (every row terminal or Blocked)
+  - the mode: FIX (rows FAIL / PARTIAL / In Progress / Needs re-verify exist, and they
+    come FIRST in the list), FRESH (nothing failing), or NOTHING (every row terminal or
+    Blocked). The working list is every open row in both FIX and FRESH: the mode says
+    what to build first, never what to leave out. A roadmap row (tf_roadmap.py) is not
+    open: it is counted and named apart, never built.
   - the working list, grouped into clusters by the checklist's page section, each
-    naming its builder from the row prefix: REQ-UI -> trblazeui, REQ-RAG -> techierag,
-    REQ-FN / REQ-NFR -> builder
+    naming its builder from the row prefix: REQ-UI -> trblazeui when the project uses
+    TrBlazeUI (else builder), REQ-RAG -> techierag, REQ-FN / REQ-NFR -> builder
   - with --prompts, one ready sub-agent prompt per cluster, filled from
     .tfcore/templates/v4custom/build-subagent-prompt.md with the rows, their acceptance
     lines, their mockups and the two standing rules.
@@ -18,7 +21,9 @@ import os
 import re
 import sys
 
-TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+# norm() drops a bracketed tail ("Verified (2026-09-01)"), so "Done (pre-existing)" arrives as "done":
+# only the bracketed spelling was listed, and AppManager's 18 finished rows went on the working list (TF-003)
+TERMINAL = {"verified", "done", "done (pre-existing)", "n/a"}
 FIX = {"fail", "partial", "in progress", "needs re-verify"}
 BLOCKED = {"blocked"}
 BUILDER = {"UI": "trblazeui", "RAG": "techierag", "FN": "builder", "NFR": "builder"}
@@ -49,6 +54,44 @@ def norm(s):
     return re.sub(r"\s*\(.*$", "", s).strip()
 
 
+def ui_builder(app):
+    """-> (builder, why) for the UI clusters: trblazeui only when the project uses TrBlazeUI.
+
+    The framework gives every project `.trblazeui/`, whether it uses the library or not, so that
+    folder says nothing: AppManager, which does not use it, had its UI rows sent to the trblazeui
+    sub-agent (TF-008). The project's own files decide: a TrBlazeUI package or project reference in
+    a .csproj or .props. Before any such file exists (a first build), the Architecture document
+    naming it decides. tests/regression/run.sh am_008."""
+    skip = {"bin", "obj", "node_modules", ".git", ".tfcore", ".claude", ".opencode", ".trblazeui",
+            ".techierag", ".artifacts"}
+    seen = 0
+    for root, dirs, files in os.walk("."):
+        dirs[:] = sorted(d for d in dirs if d not in skip)
+        for fn in sorted(files):
+            if not fn.endswith((".csproj", ".props")):
+                continue
+            seen += 1
+            p = os.path.join(root, fn)
+            if re.search(r'Include="[^"]*\bTrBlazeUI[\w.]*(?:\.csproj)?"', read(p), re.I):
+                return "trblazeui", f"{os.path.relpath(p)} references TrBlazeUI"
+    if seen:
+        return "builder", f"none of the {seen} .csproj/.props file(s) references TrBlazeUI"
+    arch = os.path.join("docs", f"{app}-Architecture.md")
+    if os.path.isfile(arch) and re.search(r"\bTrBlazeUI\b", read(arch)):
+        return "trblazeui", f"no project file yet; {arch} names TrBlazeUI"
+    return "builder", "no project file yet, and the Architecture document does not name TrBlazeUI"
+
+
+def usage_guide(app):
+    """The guide the project really has, UsageGuide or Usage-Guide: tf-verify-list.py's reader. The prompt
+    named the first spelling only, a file AppManager does not have (TF-022). tests/regression/run.sh am_022."""
+    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 vl.usage_guide(app)
+
+
 def rows_of(text):
     rows = []
     for line in text.splitlines():
@@ -110,20 +153,53 @@ def main(argv):
     if not rows:
         die(f"{cl} has no REQ rows")
     ent = entries_of(text)
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import tf_roadmap
+    import tf_defect
+    marked = tf_roadmap.ids(text)
+    roadmap = [r for r in rows if r["id"].upper() in marked and r["status"] not in TERMINAL | BLOCKED]
 
-    fix_rows = [r for r in rows if r["status"] in FIX]
-    open_rows = [r for r in rows if r["status"] not in TERMINAL | BLOCKED]
+    fix_rows = [r for r in rows if r["status"] in FIX and r not in roadmap]
+    open_rows = [r for r in rows if r["status"] not in TERMINAL | BLOCKED and r not in roadmap]
+    # Repair before new work, but never INSTEAD of it. A row can sit at `Needs re-verify`
+    # permanently -- TfLens REQ-FN-067 and -070 need a repository that emits events.ndjson
+    # and none exists, so every honest verify run re-confirms that gate rather than clearing
+    # it. FIX used to win outright, which pinned the mode forever: the twelve rows a later
+    # *amend-docs added were never once printed, and a pass that trusted the working list
+    # would have met build-phase's ending condition with twelve requirements at 0%.
+    # So the working list is every open row, and FIX only says which ones come first.
+    # tests/regression/run.sh tf_019.
     if fix_rows:
-        mode, work = "FIX", fix_rows
+        rest = [r for r in open_rows if r not in fix_rows]
+        mode, work = "FIX", fix_rows + rest
     elif open_rows:
         mode, work = "FRESH", open_rows
     else:
         mode, work = "NOTHING", []
+    # A row in FIX mode is on the list for a defect its acceptance line rarely names; a builder given
+    # only that line finds the row working and fixes nothing (AppManager TF-020). The defect rides with
+    # the row: its ⚠ clauses, else a FAIL/PARTIAL row's whole Remarks. tests/regression/run.sh am_020.
+    for r in rows:
+        r["defects"] = (tf_defect.clauses(r["remarks"]) or ([r["remarks"]] if r["status"] in {"fail", "partial"}
+                        and r["remarks"] else [])) if r in fix_rows else []
     terminal = sum(1 for r in rows if r["status"] in TERMINAL)
     blocked = [r for r in rows if r["status"] in BLOCKED]
     print(f"# tf-build-list — {app} — {cl} — phase {phase}")
-    print(f"Mode: {mode} — {len(work)} row(s) to build; {terminal} terminal, {len(blocked)} Blocked, {len(rows)} total"
+    print(f"Mode: {mode} — {len(work)} row(s) to build; {terminal} terminal, {len(blocked)} Blocked, "
+          f"{len(roadmap)} roadmap, {len(rows)} total"
           + (f" — {', '.join(r['id'] for r in work[:8])}{' …' if len(work) > 8 else ''}" if work else ""))
+    # Every row is in exactly one of the five counts, and the arithmetic is printed so a
+    # reader can check it rather than trust it. A row missing from all of them is the
+    # failure this line exists to make impossible.
+    if len(work) + terminal + len(blocked) + len(roadmap) != len(rows):
+        print(f"⚠ {len(rows) - len(work) - terminal - len(blocked) - len(roadmap)} row(s) are in no category — "
+              "the checklist carries a status this script does not know; fix the row or the script")
+    if roadmap:
+        print("Roadmap, not in this phase's scope (not built; the owner moves them with *amend-docs): "
+              + ", ".join(r["id"] for r in roadmap))
+    if fix_rows and len(work) > len(fix_rows):
+        print(f"Order: {len(fix_rows)} failing row(s) first ({', '.join(r['id'] for r in fix_rows)}), "
+              f"then {len(work) - len(fix_rows)} not yet started")
     if blocked:
         print("Blocked (library gaps, pass through unless the feedback entry is resolved): " + ", ".join(r["id"] for r in blocked))
     if not work:
@@ -131,10 +207,14 @@ def main(argv):
         return 0
 
     clusters = {}
+    builder = dict(BUILDER)
+    if any(r["id"].upper().startswith("REQ-UI-") for r in work):
+        builder["UI"], why = ui_builder(app)
+        print(f"UI rows go to: {builder['UI']} — {why}")
     for r in work:
         sec, acc, mock, brd = ent.get(r["id"].upper(), ("Other", "", "", ""))
         cls = re.match(r"REQ-(UI|FN|RAG|NFR)-", r["id"]).group(1)
-        key = ("Non-functional" if cls == "NFR" else "RAG" if cls == "RAG" else sec, BUILDER[cls])
+        key = ("Non-functional" if cls == "NFR" else "RAG" if cls == "RAG" else sec, builder[cls])
         clusters.setdefault(key, []).append((r, acc, mock, brd))
     print()
     print("## Clusters (one sub-agent each; spawn them all in one turn)")
@@ -154,6 +234,8 @@ def main(argv):
             print(f"- {r['id']} [{label}/{builder}] {r['title']} — {r['status']}{todo}")
             if acc:
                 print(f"    Acceptance: {acc}")
+            for x in r["defects"]:
+                print(f"    Defect: {x}")
             if mock:
                 print(f"    Mockup: {mock}")
     if not prompts:
@@ -164,18 +246,24 @@ def main(argv):
         die(f"template {TPL} does not exist at its literal path")
     tpl = read(TPL)
     tpl = re.sub(r"<!--.*?-->\s*", "", tpl, flags=re.S)
+    guide = usage_guide(app)
     for label, sec, builder, items in named:
         lines = []
         for r, acc, mock, brd in items:
             lines.append(f"- {r['id']} — {r['title']}" + (f" ({brd})" if brd else ""))
             lines.append(f"  Acceptance: {acc or 'MISSING — refuse the row and report it'}")
+            lines.extend(f"  Defect: {x}" for x in r["defects"])
             if mock:
                 lines.append(f"  Mockup: {mock}")
+        if any(r["defects"] for r, *_ in items):
+            lines.append("\nA row with a Defect line is on this list for that defect. Fix every one at the file and "
+                         "line it names, keep the acceptance line true, and replace the row's Remarks: a row that "
+                         "already passes its acceptance line is not done while its defect stands.")
         mocks = sorted({m for _r, _a, m, _b in items if m})
         body = (tpl.replace("{App}", app).replace("{Cluster}", label).replace("{Builder}", builder)
                 .replace("{Section}", sec).replace("{Rows}", "\n".join(lines))
                 .replace("{Mockups}", ", ".join(mocks) if mocks else "none (not a UI cluster)")
-                .replace("{Checklist}", cl))
+                .replace("{Checklist}", cl).replace("{UsageGuide}", guide))
         print()
         print(f"## Prompt for cluster {label} [{builder}]")
         print(body.strip())

package/.tfcore/utils/tf-build-list.sh

@@ -6,9 +6,11 @@
 #   bash .tfcore/utils/tf-build-list.sh MyApp --phase 2     # a later phase of a Large project
 #
 # Reads the phase's checklist (appPhase in core-config.yaml unless --phase). Rows FAIL /
-# PARTIAL / In Progress / Needs re-verify make it FIX mode over exactly those rows; else every
-# open row is FRESH; Blocked rows pass through. Clusters follow the checklist's page sections,
-# each with its builder from the prefix (UI -> trblazeui, RAG -> techierag, FN/NFR -> builder).
+# PARTIAL / In Progress / Needs re-verify make it FIX mode, which puts those rows FIRST and
+# then lists every other open row; FRESH is the same list when nothing is failing; Blocked rows
+# pass through. Clusters follow the checklist's page sections,
+# each with its builder from the prefix (UI -> trblazeui when the project references TrBlazeUI,
+# else builder; RAG -> techierag; FN/NFR -> builder).
 # Prompts are filled from .tfcore/templates/v4custom/build-subagent-prompt.md.
 # Writes nothing. Thin wrapper over tf-build-list.py; Python 3 stdlib only.
 set -uo pipefail