@techierathore/techieflow 1.0.4 → 1.1.1

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

@@ -7,10 +7,11 @@ Reads the phase's checklist (appPhase in core-config.yaml, or --phase) and print
   - 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.
+    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.
@@ -20,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"}
@@ -51,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():
@@ -112,9 +153,14 @@ 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
@@ -130,17 +176,27 @@ def main(argv):
         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 four counts, and the arithmetic is printed so a
+    # 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(rows):
-        print(f"⚠ {len(rows) - len(work) - terminal - len(blocked)} row(s) are in no category — "
+    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")
@@ -151,11 +207,30 @@ 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}")
+    # A defect on a screen goes to one builder. Split by builder, the UI and the backend clusters of one
+    # page both carried its mockup defect, both edited the same files at once, and one left a component
+    # half-written that broke every other builder's boot for an hour (Chatur TF-004). Such a page is
+    # one cluster, built by the UI builder when one of its UI rows carries the defect.
+    cls_of = {r["id"]: re.match(r"REQ-(UI|FN|RAG|NFR)-", r["id"]).group(1) for r in work}
+    sec_of = {r["id"]: ent.get(r["id"].upper(), ("Other", "", "", ""))[0] for r in work}
+    fixed = {}
+    for r in work:
+        s, cls = sec_of[r["id"]], cls_of[r["id"]]
+        if r["defects"] and cls in ("UI", "FN") and (cls == "UI" or s not in fixed):
+            fixed[s] = builder[cls]
     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])
+        who = fixed[sec] if cls in ("UI", "FN") and sec in fixed else builder[cls]
+        key = ("Non-functional" if cls == "NFR" else "RAG" if cls == "RAG" else sec, who)
         clusters.setdefault(key, []).append((r, acc, mock, brd))
+    for s in sorted(fixed):
+        if builder["UI"] != builder["FN"] and {"UI", "FN"} <= {cls_of[r["id"]] for r in work if sec_of[r["id"]] == s}:
+            print(f"One builder for {s}: it carries a defect, so its UI and backend rows go to {fixed[s]} together")
     print()
     print("## Clusters (one sub-agent each; spawn them all in one turn)")
     letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
@@ -174,6 +249,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:
@@ -184,18 +261,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

@@ -9,7 +9,8 @@
 # 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, RAG -> techierag, FN/NFR -> builder).
+# 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