@techierathore/techieflow 1.1.0 → 1.2.0

package/.tfcore/utils/tf-owner-text.py

@@ -59,13 +59,31 @@ def load_words(root):
 
 
 def upstream_state(root):
-    """Every entry id in the project's feedback files -> (state, where), from the one reader
-    every script uses (tf_feedback.py), so this check and PROJECT-STATUS can never disagree."""
+    """Every entry id in the project's feedback files -> [(state, where, names)], one per file, from
+    the one reader every script uses (tf_feedback.py), so this check and PROJECT-STATUS can never disagree."""
     sys.path.insert(0, HERE)
     import tf_feedback
     return tf_feedback.state_map(root)
 
 
+def resolve(rid, cands, unit, text):
+    """The feedback file an id in this unit means (TrBlazeUI TF-006). One file holding it: that one.
+    Several: the files whose project the unit names ("Lekhak TR-002"), else the files the whole text
+    names. -> (state, where), or (None, the files) when it stays several that disagree."""
+    if len(cands) == 1:
+        return cands[0][:2]
+    for txt in (unit, text):
+        # a name every candidate file shares (the library's own) says nothing about which one
+        shared = set.intersection(*(set(c[2]) for c in cands))
+        hit = [c for c in cands if any(n not in shared and re.search(rf"(?<![\w-]){re.escape(n)}(?![\w-])", txt) for n in c[2])]
+        if hit:
+            cands = hit
+            break
+    if len({c[0] for c in cands}) == 1:
+        return cands[0][:2]
+    return None, ", ".join(c[1].split(",")[0] for c in cands)
+
+
 def split_text(text):
     """-> (prose lines [(n, line)], the text inside code blocks)."""
     prose, fenced, fence = [], [], None
@@ -142,9 +160,13 @@ def check(text, label, root, final=False, words=None, ups=None):
     for n, txt, header in us:
         for rid in dict.fromkeys(ANY_ID.findall(txt)):
             if rid in ups:
-                mentions.setdefault(rid, []).append((n, txt, header))
-    for rid, ms in sorted(mentions.items(), key=lambda kv: kv[1][0][0]):
-        st, where = ups[rid]
+                st, where = resolve(rid, ups[rid], txt, text)
+                if st is None:
+                    fail(n, f'{rid} is an entry in several feedback files ({where}); name whose it is with the id, '
+                            f'as in "{ups[rid][0][2][0]} {rid}"')
+                    continue
+                mentions.setdefault((rid, st, where), []).append((n, txt, header))
+    for (rid, st, where), ms in sorted(mentions.items(), key=lambda kv: kv[1][0][0]):
         if st in ("fixed", "closed"):
             # read the sentence that names it, or its table row: "TF-901 is filed. X is fixed." is wrong
             said = lambda txt, h: [txt] if h is not None else [s for s in re.split(r"(?<=[.!?])\s+", txt) if rid in s]

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

@@ -42,12 +42,25 @@ case "${1:-}" in
     # the outer command as "outer", written FIRST so a greedy `.*"started":"…"` read still takes this
     # command's own start. tf-verify-emit.sh and tf-fix-close.sh read it to tell the two starts
     # apart (TF-052: the inline verify took the fix's start and its record swallowed the fix's).
-    OUTER=""
+    OUTER=""; CHAINED=""
     if [[ -f "$FILE" && -z "$(find "$FILE" -mmin +1440 2>/dev/null)" ]]; then
       OC="$(sed -n 's/.*"cmd":"\([^"]*\)".*/\1/p' "$FILE")"; OA="$(sed -n 's/.*"app":"\([^"]*\)".*/\1/p' "$FILE")"
       OS="$(sed -n 's/.*"started":"\([^"]*\)".*/\1/p' "$FILE")"
       [[ -n "$OC" && -n "$OS" && "$OC" != "$CMD" && "$OC" != "goal" && "$OS" != "$NOW" ]] \
         && OUTER="\"outer\":{\"cmd\":\"$OC\",\"app\":\"$OA\",\"started\":\"$OS\"},"
+      # A command the task files run inside another one keeps the outer command's document baseline
+      # (TrBlazeUI TF-002: *triage-and-fix started verify-phase and metrics-report, each wrote a new
+      # baseline, and the rows the triage had just added had their findings relabelled OLD). The pairs
+      # are the chains the task files name: build-phase, fix-issues and triage-and-fix run verify-phase;
+      # triage-and-fix runs metrics-report. The marker is never ended, so a standalone verify after a
+      # fix also keeps the fix's baseline: that can only make the gate stricter, never hide a finding.
+      OOC="$(sed -n 's/^{"outer":{"cmd":"\([^"]*\)".*/\1/p' "$FILE")"
+      case "$CMD" in
+        verify-phase|metrics-report)
+          for c in "$OC" "$OOC"; do
+            case "$c" in build-phase|fix-issues|triage-and-fix) CHAINED="$c"; break ;; esac
+          done ;;
+      esac
     fi
     printf '{%s"cmd":"%s","app":"%s","started":"%s"}\n' "$OUTER" "$CMD" "$APP" "$NOW" > "$FILE"
     echo "$NOW"
@@ -56,10 +69,17 @@ case "${1:-}" in
     # status file already carry when the command starts are recorded, so the gate and the Stop
     # hook block only on findings this command introduces (Schemas §7.1 decision 8: old projects
     # are repaired through *amend-docs, never by whichever command happens to run next).
-    if [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+    if [[ -n "$CHAINED" ]]; then
+      echo "tf-phase: $CMD runs inside $CHAINED — keeping its document baseline (findings since $CHAINED started stay FAIL)" >&2
+    elif [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+      # Every file `tf-doc-check.sh --app` reads, not only the checklists and the status file: *amend-docs
+      # and day-1 close on `--app`, so the BRD's, the Architecture's and the mockups' old findings read
+      # as new and blocked the run (Lekhak TF-023, 131 of them). A baseline only relabels what was
+      # already there, so a finding the command introduces still FAILs.
       docs=(); for f in "$ROOT"/docs/*-Checklist.md "$ROOT"/PROJECT-STATUS.md; do [[ -f "$f" ]] && docs+=("$f"); done
-      if [[ ${#docs[@]} -gt 0 ]]; then
-        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write "${docs[@]}" 2>/dev/null | tail -1 >&2 ) || true
+      appargs=(); [[ -n "$APP" && -d "$ROOT/docs" ]] && appargs=(--app "$APP")
+      if [[ ${#docs[@]} -gt 0 || ${#appargs[@]} -gt 0 ]]; then
+        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write ${appargs[@]+"${appargs[@]}"} ${docs[@]+"${docs[@]}"} 2>/dev/null | tail -1 >&2 ) || true
       fi
     fi
     # The framework's own scripts, against THIS project's real files, before the command

package/.tfcore/utils/tf-render-html.py

@@ -101,6 +101,20 @@ class Slugger(object):
         self.seen[s] = c
         return s if c == 1 else "%s-%d" % (s, c)
 
+    def github(self, text):
+        """The id GitHub gives the same heading, which a markdown table of contents links to: digits
+        kept, punctuation dropped, spaces to hyphens, a repeat suffixed -1, -2 (AppManager TF-029:
+        `### 3.7 Group Service (GroupSvc)` is #37-group-service-groupsvc there, #group-service-groupsvc
+        here, so every numbered TOC link in the rendered guide went nowhere)."""
+        if not hasattr(self, "gh_seen"):
+            self.gh_seen = {}
+        s = re.sub(r"<[^>]+>", "", text)
+        s = re.sub(r"[*`~]", "", s).strip().lower()
+        s = re.sub(r"[^\w\- ]", "", s, flags=re.UNICODE).replace(" ", "-")
+        c = self.gh_seen.get(s, 0)
+        self.gh_seen[s] = c + 1
+        return s if c == 0 else "%s-%d" % (s, c)
+
 
 # ----------------------------------------------------------------------------
 # Inline conversion
@@ -205,11 +219,13 @@ class Renderer(object):
 
     def heading(self, level, text):
         slug = self.sl.slug(text)
+        gh = self.sl.github(text)      # every level, so its repeat count matches GitHub's
         if level in (2, 3, 4):
-            self.emit('<h%d id="%s">%s<a class="anchor-link" href="#%s">#</a></h%d>'
-                      % (level, slug, inline(text), slug, level))
+            alias = '<a id="%s"></a>' % gh if gh and gh != slug else ""
+            self.emit('<h%d id="%s">%s%s<a class="anchor-link" href="#%s">#</a></h%d>'
+                      % (level, slug, alias, inline(text), slug, level))
         else:
-            self.emit("<h%d>%s</h%d>" % (level, inline(text), level))
+            self.emit("<h%d%s>%s</h%d>" % (level, ' id="%s"' % gh if gh else "", inline(text), level))
         if level == 2:
             self.h2 += 1
         if level in (2, 3):

package/.tfcore/utils/tf-req-ids.py

@@ -0,0 +1,36 @@
+"""tf-req-ids.py — which rows a test's name claims (Chatur TF-012). Imported by tf-verify-tests.sh.
+
+A test proves the ids its name STARTS with, nothing else. An xUnit theory reported as
+`REQ-UI-048 requirement ids are found in test names(aName: "REQ-FN-053 …")` passed REQ-FN-053 and
+REQ-FN-055, which no test had ever touched. The ids are read from the leading run of REQ tokens
+(separated by spaces, commas, slashes, "and" …, after at most one short capital tag such as FIX or
+UAT), before any argument list. An id named later in the name is the test's subject matter, not its
+claim. A theory whose argument is NAMED for the row it proves (`row: "REQ-RAG-125"`, also req, reqId,
+requirement) claims that row: TechieRag's per-row cases.
+"""
+import re
+
+ID = re.compile(r"(REQ-(?:UI|FN|NFR|RAG)-\d{3})", re.I)
+LEAD_SEP = re.compile(r"(?:[\s,;/&+|·:\[\]–—-]|\band\b)*", re.I)
+TAG = re.compile(r"\s*\[?[A-Z][A-Z0-9]{1,5}\]?:?\s+(?=REQ-)")
+ROW_ARG = re.compile(r"\b(?:row|req|reqid|req_id|requirement)\s*[:=]\s*[\"']?(REQ-(?:UI|FN|NFR|RAG)-\d{3})\b", re.I)
+
+
+def ids_of(name):
+    """the ids one name claims, in order"""
+    name = str(name or "")
+    head, out = name.split("(", 1)[0], [x.upper() for x in ROW_ARG.findall(name)]
+    t = TAG.match(head)
+    p = t.end() if t else 0
+    while True:
+        p = LEAD_SEP.match(head, p).end()
+        m = ID.match(head, p)
+        if not m:
+            return out
+        out.append(m.group(1).upper())
+        p = m.end()
+
+
+def mentioned(name):
+    """every id the name carries anywhere"""
+    return {x.upper() for x in ID.findall(str(name or ""))}

package/.tfcore/utils/tf-stack-check.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# tf-stack-check.sh — does the code use the packages the Architecture requires? See tf_stack_check.py.
+exec python3 "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/tf_stack_check.py" "$@"

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

@@ -14,7 +14,10 @@ into the template (.tfcore/templates/v4custom/app-project-status-tmpl.md):
   - the Open requirements section (counts by status, at most ten named rows)
   - the Verification log table with its new row (last five kept)
   - the Library feedback summary lines
-  - the Next command to run, in both harness forms, and why
+  - the Next command to run, in both harness forms, and why. On a project with more than one
+    phase a verify names its phase (`*verify ui <App> --phase 3`), and built rows waiting in
+    another phase's checklist are found too: `--phase N` for one, `--phase all` for several
+    (Sevak TF-005). A build of this phase still comes first.
 
 Writes nothing. The agent writes PROJECT-STATUS.md with the harness Write tool.
 Python 3 standard library only. Exit 0 printed, 2 could not run.
@@ -170,8 +173,19 @@ def existing_log_rows(status_text):
     return rows
 
 
-def handoff_ran(log_rows):
-    return any("handoff" in r.lower() for r in log_rows)
+def handoff_ran(log_rows, app="", phase=1):
+    """A handoff of THIS phase: a log row naming handoff whose status-table cell names this phase's
+    checklist. Phase 2's handoff counted for phase 3, so a newly built phase read "handoff done" and
+    sent the owner to UAT with guides that did not describe it (TechieRag TF-003). A row naming no
+    checklist (an older log) counts in phase 1 only, where nothing else could be meant."""
+    own = f"{phase_prefix(app, phase)}Checklist.md" if app else ""
+    for r in log_rows:
+        if "handoff" not in r.lower():
+            continue
+        named = re.findall(r"[\w.-]+-Checklist\.md", r)
+        if (own in named) if named and own else (phase <= 1):
+            return True
+    return False
 
 
 def feedback_lines(root, app):
@@ -193,6 +207,13 @@ def config_phase(root):
     return 1
 
 
+def config_library(root):
+    """metrics.project_type: library (or appKind: library): the documents ship inside the package."""
+    p = os.path.join(root, ".tfcore", "core-config.yaml")
+    t = read(p) if os.path.isfile(p) else ""
+    return bool(re.search(r"(?m)^\s+project_type:\s*['\"]?lib", t) or re.search(r"(?m)^appKind:\s*['\"]?lib", t))
+
+
 def phase_prefix(app, phase):
     return f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
 
@@ -222,9 +243,39 @@ def usage_guide(app):
     return vl.usage_guide(app)
 
 
-def next_command(app, rows, log_rows, phase=1, verdicts=None):
-    """Returns (phase, qualifier, cc_line, oc_line, reason)."""
+def to_verify(rows, verdicts):
+    """(waiting, unmeasured): built rows a verify should grade, and built rows the last verify could
+    not measure (every test skipped). Roadmap rows and rows carrying a defect are neither."""
+    built = [r for r in rows if not r.get("roadmap") and r["status"].lower() in BUILT and not has_defect(r)]
+    unmeasured = [r for r in built if verdicts.get(r["id"]) == "NOT-TESTED"]
+    return [r for r in built if r not in unmeasured], unmeasured
+
+
+def scope_of(rows):
+    ui = [r for r in rows if r["id"].startswith("REQ-UI")]
+    return "ui" if len(ui) == len(rows) else ("functional" if not ui else "all")
+
+
+def other_phases(root, app, phase_n, verdicts):
+    """{phase: rows waiting for a verify} for every other phase with a checklist (Sevak TF-005: phases 1
+    and 2 held 86 rows waiting while the status read only phase 3's checklist)."""
+    found = {}
+    for f in sorted(os.listdir(os.path.join(root, "docs"))) if os.path.isdir(os.path.join(root, "docs")) else []:
+        m = re.fullmatch(re.escape(app) + r"-(?:P(\d+)-)?Checklist\.md", f)
+        p = int(m.group(1) or 1) if m else 0
+        if not p or p == phase_n:
+            continue
+        waiting, _ = to_verify(checklist_rows(read(os.path.join(root, "docs", f))), verdicts)
+        if waiting:
+            found[p] = waiting
+    return dict(sorted(found.items()))
+
+
+def next_command(app, rows, log_rows, phase=1, verdicts=None, library=False, multi=False):
+    """Returns (phase, qualifier, cc_line, oc_line, reason). multi: the project has more than one
+    phase, so a verify names the phase it grades."""
     verdicts = verdicts or {}
+    pflag = f" --phase {phase}" if multi else ""
 
     def ids(lst):
         return ", ".join(r["id"] for r in lst[:6]) + (" …" if len(lst) > 6 else "")
@@ -242,7 +293,8 @@ def next_command(app, rows, log_rows, phase=1, verdicts=None):
     now = [r for r in rows if not r.get("roadmap")]
     unbuilt = [r for r in now if r["status"].lower() not in TERMINAL | PASS_THROUGH | BUILT | OWNER]
     defects = [r for r in now if has_defect(r)]
-    built = [r for r in now if r["status"].lower() in BUILT and r not in defects]
+    waiting, unmeasured = to_verify(now, verdicts)
+    built = waiting + unmeasured
     owner = [r for r in now if r["status"].lower() in OWNER]
     verified, counted, na = figures(rows)
     q = f"{verified} of {counted} verified" + (f", {na} not applicable" if na else "")
@@ -262,31 +314,34 @@ def next_command(app, rows, log_rows, phase=1, verdicts=None):
         # loop that looks like progress. Say what it actually needs: data, a changed
         # acceptance line, or the row marked N/A. Only the owner can choose. FR-69's sibling
         # case; the verdicts come from the ledger the verifier already writes.
-        unmeasured = [r for r in built if verdicts.get(r["id"]) == "NOT-TESTED"]
-        waiting = [r for r in built if r not in unmeasured]
         if unmeasured and not waiting:
             line = (f"(owner) {len(unmeasured)} row(s) cannot be measured here — create the data, "
                     f"change the acceptance line, or mark the row N/A: {ids(unmeasured)}")
             return ("Verify", f"{len(unmeasured)} not measurable, {q}", line, line,
                     f"every test carrying these ids was skipped, so another verify run changes nothing: {ids(unmeasured)}")
-        ui = [r for r in waiting if r["id"].startswith("REQ-UI")]
-        scope = "ui" if len(ui) == len(waiting) else ("functional" if not ui else "all")
+        scope = scope_of(waiting)
         reason = f"{len(waiting)} rows are built and not verified: {ids(waiting)}"
         if unmeasured:
             reason += (f"; {len(unmeasured)} more could not be measured (every test skipped) "
                        f"and need the owner: {ids(unmeasured)}")
         return ("Verify", f"{len(waiting)} to verify, {q}",
-                f"{CC}verifier *verify {scope} {app}", f"{OC}flow-verifier *verify {scope} {app}",
+                f"{CC}verifier *verify {scope} {app}{pflag}", f"{OC}flow-verifier *verify {scope} {app}{pflag}",
                 reason)
     if owner:
-        if handoff_ran(log_rows):
+        if handoff_ran(log_rows, app, phase):
             line = f"(owner-run) {usage_guide(app)} — {ids(owner)}"
             return ("UAT", f"{len(owner)} owner-run, {q}", line, line,
                     f"{len(owner)} rows are Owner-UAT and handoff has run; the owner closes them")
         return ("Handoff", f"{len(owner)} owner-run, {q}",
                 f"{CC}flow-master *handoff-phase {app}", f"{OC}flow-master *handoff-phase {app}",
                 f"{len(owner)} rows are Owner-UAT and handoff has not run yet")
-    if handoff_ran(log_rows):
+    if handoff_ran(log_rows, app, phase):
+        if library:
+            # a library's fix runs the handoff steps itself, before the gate, so the package ships with
+            # its documents; *handoff-phase after the release was the wrong order (TrBlazeUI TF-005)
+            line = "(owner) commit, then build and publish the package — its shipped documents are current; no agent command"
+            return ("Release", f"handoff done, {q}", line, line,
+                    "every row in this phase's scope is terminal and the shipped documents were brought up to date")
         line = "(owner) set current_phase to Released after UAT — no agent command"
         return ("UAT", f"handoff done, {q}", line, line,
                 "every row in this phase's scope is terminal and handoff has run; waiting on the owner")
@@ -320,12 +375,32 @@ def main(argv):
     st_text = read(st_path) if os.path.isfile(st_path) else ""
     log_rows = existing_log_rows(st_text)
     vdate, vresult = last_verify(root, app)
-    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n, ledger_verdicts(root))
+    verdicts = ledger_verdicts(root)
+    others = other_phases(root, app, phase_n, verdicts)
+    pname, ptotal = phase_row(root, app, phase_n)
+    multi = phase_n > 1 or (ptotal or 0) > 1 or bool(others)
+    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n, verdicts, config_library(root), multi)
+    if others:
+        # A verify of another phase names that phase, or --phase all when several phases wait; a build
+        # of this phase still goes first.
+        n = sum(len(w) for w in others.values())
+        where = "; ".join(f"phase {p}: {len(w)} ({', '.join(r['id'] for r in w[:4])}{' …' if len(w) > 4 else ''})"
+                          for p, w in others.items())
+        mine, _ = to_verify(rows, verdicts)
+        if phase == "Build":
+            reason += f"; after this build, {n} built rows of other phases wait for a verify — {where}"
+        else:
+            pick = list(others) + ([phase_n] if mine else [])
+            flag = f"--phase {pick[0]}" if len(pick) == 1 else "--phase all"
+            scope = scope_of([r for w in others.values() for r in w] + mine)
+            cc, oc = f"{CC}verifier *verify {scope} {app} {flag}", f"{OC}flow-verifier *verify {scope} {app} {flag}"
+            reason = (f"{n} rows of other phases are built and not verified — {where}"
+                      + (f"; and in this phase: {reason}" if phase == "Verify" else f"; this phase alone would be: {qual} ({reason})"))
+            phase, qual = "Verify", f"{n + len(mine)} to verify across phases {', '.join(map(str, sorted(pick)))}, {qual}"
     roadmap = [r["id"] for r in rows if r["roadmap"]]
     if roadmap:
         reason += (f"; {len(roadmap)} roadmap row(s) are not in this phase's scope and are left for the owner "
                    f"(*amend-docs): {', '.join(roadmap)}")
-    pname, ptotal = phase_row(root, app, phase_n)
     if ptotal or phase_n > 1:
         tag = f"Phase {phase_n} of {ptotal or '?'}" + (f" ({pname})" if pname else "")
         phase = f"{tag} · {phase}"

package/.tfcore/utils/tf-theme.mjs

@@ -0,0 +1,189 @@
+// tf-theme.mjs — draw a page in its light or its dark theme, and measure what a reader sees in it.
+// Shared by tf-verify-screens and tf-mockup-parity, as tf-login.mjs is (Lekhak TF-024).
+//
+// Why: every screen was graded in light mode only. Lekhak's owner then found 20 of 20 desktop admin
+// screens unreadable in dark mode (text at 1.03 : 1, white panels inside a dark shell), all Verified.
+//
+// A theme is put on a page the two ways a stack listens for one, knowing nothing about the stack:
+//   - the browser's colour scheme (prefers-color-scheme), emulated;
+//   - the light/dark value of every data-*theme/mode/scheme attribute on <html> and <body>, and the
+//     light/dark mode classes there (dark, theme-dark …). A page that declares none is given
+//     data-theme and data-bs-theme; a page with no such class is given, for dark, the class `dark`
+//     (Tailwind's switch, and the one an app setting data-theme and the class together also reads).
+// Each call returns a function that puts the page back the way it was: an attached desktop head is
+// the viewer's app. A page whose painted surface does not change between the two has no dark theme;
+// `surface` and `differs` tell. `audit` is the contrast rule the visual check applies.
+
+export const THEMES = ['light', 'dark'];
+
+// --themes light,dark | light | dark | auto (the default: light, and dark when the app has one)
+export function parseThemes(v) {
+  const s = String(v || 'auto').toLowerCase().trim();
+  if (s === 'auto') return null;
+  const t = [...new Set(s.split(',').map((x) => x.trim()).filter((x) => THEMES.includes(x)))];
+  return t.length ? t : null;
+}
+
+const FORCE = (want) => {
+  const MODE = /^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i;
+  const other = want === 'dark' ? /light/ig : /dark/ig;
+  const before = [];
+  let declared = false, classed = false;
+  for (const [where, el] of [['html', document.documentElement], ['body', document.body]]) {
+    if (!el) continue;
+    for (const a of [...el.attributes]) {
+      if (!/^data-.*(theme|mode|scheme)/i.test(a.name) || !/(dark|light)/i.test(a.value)) continue;
+      declared = true;
+      before.push({ where, attr: a.name, value: a.value });
+      el.setAttribute(a.name, a.value.replace(other, want));
+    }
+    const toks = [...el.classList].filter((c) => MODE.test(c));
+    if (toks.length) {
+      declared = classed = true;
+      before.push({ where, cls: toks });
+      for (const c of toks) { el.classList.remove(c); el.classList.add(c.replace(other, want)); }
+    }
+  }
+  if (!declared) {
+    const h = document.documentElement;
+    for (const name of ['data-theme', 'data-bs-theme']) {
+      if (h.hasAttribute(name)) continue;            // a theme by name (data-theme="corporate") is left alone
+      before.push({ where: 'html', attr: name, value: null });
+      h.setAttribute(name, want);
+    }
+  }
+  // a page with no light/dark class gets `dark` for the dark pass even when it declared data-theme:
+  // an app whose switch sets both (Lekhak) was otherwise drawn half dark, a state it never shows (Lekhak TF-033)
+  const h = document.documentElement;
+  if (want === 'dark' && !classed && !h.classList.contains('dark')) { before.push({ where: 'html', added: 'dark' }); h.classList.add('dark'); }
+  return before;
+};
+
+const RESTORE = (before) => {
+  for (const b of [...before].reverse()) {
+    const el = b.where === 'body' ? document.body : document.documentElement;
+    if (!el) continue;
+    if (b.added) el.classList.remove(b.added);
+    else if (b.cls) {
+      for (const c of [...el.classList]) if (/^(?:(?:theme|mode|scheme|color)[-_])?(?:dark|light)(?:[-_](?:theme|mode|scheme))?$/i.test(c)) el.classList.remove(c);
+      for (const c of b.cls) el.classList.add(c);
+    } else if (b.value === null) el.removeAttribute(b.attr);
+    else el.setAttribute(b.attr, b.value);
+  }
+};
+
+// Draws the page in `want` and returns the function that puts it back.
+export async function useTheme(page, want, settle = 350) {
+  await page.emulateMedia({ colorScheme: want }).catch(() => {});
+  const before = await page.evaluate(FORCE, want).catch(() => null);
+  if (settle) await page.waitForTimeout(settle);
+  return async () => {
+    if (before) await page.evaluate(RESTORE, before).catch(() => {});
+    await page.emulateMedia({ colorScheme: null }).catch(() => {});
+  };
+}
+
+// The luminance painted at five points of the window (and behind <body>), 0 = black, 1 = white.
+const SURFACE = () => {
+  // the browser converts the colour, never a regex: a page themed in oklch() reads back as "oklch(…)",
+  // which an rgb() pattern skipped, so every surface counted as white and no dark theme was seen (Sevak TF-005)
+  const cv = document.createElement('canvas'); cv.width = cv.height = 1;
+  const cx = cv.getContext('2d', { willReadFrequently: true });
+  const parse = (c) => { if (!c || c === 'transparent' || !cx) return null; cx.clearRect(0, 0, 1, 1); cx.fillStyle = 'rgba(0,0,0,0)'; cx.fillStyle = String(c); cx.fillRect(0, 0, 1, 1); const d = cx.getImageData(0, 0, 1, 1).data; return [d[0], d[1], d[2], d[3] / 255]; };
+  const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); };
+  const behind = (el) => {
+    const layers = [];
+    for (let e = el; e; e = e.parentElement) { const c = parse(getComputedStyle(e).backgroundColor); if (c && c[3] > 0) { layers.push(c); if (c[3] >= 0.99) break; } }
+    let out = layers.length && layers[layers.length - 1][3] >= 0.99 ? layers.pop() : [255, 255, 255, 1];
+    while (layers.length) { const t = layers.pop(), a = t[3]; out = [t[0] * a + out[0] * (1 - a), t[1] * a + out[1] * (1 - a), t[2] * a + out[2] * (1 - a), 1]; }
+    return out;
+  };
+  const w = window.innerWidth, h = window.innerHeight;
+  const pts = [[0.5, 0.5], [0.2, 0.3], [0.8, 0.3], [0.2, 0.8], [0.8, 0.8]];
+  return [document.body, ...pts.map(([x, y]) => document.elementFromPoint(x * w, y * h))].map((el) => (el ? +lum(behind(el)).toFixed(3) : null));
+};
+export const surface = (page) => page.evaluate(SURFACE).catch(() => null);
+// two surface readings differ when any point's luminance moved by more than 0.15
+export const differs = (a, b) => !!a && !!b && a.some((x, i) => x !== null && b[i] !== null && Math.abs(x - b[i]) > 0.15);
+// a reading that is mostly dark: the theme a mockup that declares none is drawn in
+export const looksDark = (s) => !!s && s.filter((x) => x !== null && x < 0.2).length > s.filter((x) => x !== null).length / 2;
+
+// The contrast rule (Lekhak TF-024), measured on what is painted:
+//   - every visible text run and form-field value reaches `min` : 1 (3.0, WCAG AA for large text)
+//     against the first opaque background behind it; disabled controls are exempt, as WCAG exempts
+//     them, and text over an image or a gradient is not measured (the colour behind it is not one);
+//   - in dark mode, no box larger than 2% of the window paints a background lighter than 0.8
+//     relative luminance (a white card or panel left in a dark shell).
+// Returns { low: [...], light: [...], low_n, light_n }, each list cut to `cap`.
+const AUDIT = ({ dark, min, cap }) => {
+  const cv = document.createElement('canvas'); cv.width = cv.height = 1;   // oklch() and every other syntax, as SURFACE
+  const cx = cv.getContext('2d', { willReadFrequently: true });
+  const parse = (c) => { if (!c || c === 'transparent' || !cx) return null; cx.clearRect(0, 0, 1, 1); cx.fillStyle = 'rgba(0,0,0,0)'; cx.fillStyle = String(c); cx.fillRect(0, 0, 1, 1); const d = cx.getImageData(0, 0, 1, 1).data; return [d[0], d[1], d[2], d[3] / 255]; };
+  const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); };
+  const ratio = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
+  const blend = (t, u) => { const a = t[3]; return [t[0] * a + u[0] * (1 - a), t[1] * a + u[1] * (1 - a), t[2] * a + u[2] * (1 - a), 1]; };
+  const behind = (el) => {
+    const layers = [];
+    for (let e = el; e; e = e.parentElement) {
+      const cs = getComputedStyle(e);
+      if (cs.backgroundImage && cs.backgroundImage !== 'none') return null;   // an image or a gradient
+      const c = parse(cs.backgroundColor);
+      if (c && c[3] > 0) { layers.push(c); if (c[3] >= 0.99) break; }
+    }
+    let out = layers.length && layers[layers.length - 1][3] >= 0.99 ? layers.pop() : [255, 255, 255, 1];
+    while (layers.length) out = blend(layers.pop(), out);
+    return out;
+  };
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    if (r.width < 2 || r.height < 2) return false;
+    for (let e = el; e; e = e.parentElement) {
+      const s = getComputedStyle(e);
+      if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) < 0.1) return false;
+    }
+    return r.bottom > 0 && r.right > 0;
+  };
+  const where = (el) => {
+    const id = el.getAttribute('data-testid');
+    const cls = String(el.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
+    return `${el.tagName.toLowerCase()}${id ? `[data-testid=${id}]` : ''}${cls ? '.' + cls : ''}`;
+  };
+  const rgb = (c) => `rgb(${c.slice(0, 3).map(Math.round).join(',')})`;
+  const EXEMPT = '[disabled],[aria-disabled="true"],svg,script,style,noscript,template';
+  const low = [], light = [], seen = new Set();
+  const measure = (el, text) => {
+    const fg = parse(getComputedStyle(el).color);
+    if (!fg || fg[3] < 0.05) return;
+    const bg = behind(el);
+    if (!bg) return;
+    const r = ratio(blend(fg, bg), bg);
+    const key = where(el) + '|' + text.slice(0, 30);
+    if (r < min && !seen.has(key)) { seen.add(key); low.push({ text: text.slice(0, 40), fg: rgb(fg), bg: rgb(bg), ratio: Math.round(r * 100) / 100, where: where(el) }); }
+  };
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    const text = (n.textContent || '').trim();
+    const el = n.parentElement;
+    if (!text || !el || !/[\p{L}\p{N}]/u.test(text) || el.closest(EXEMPT) || !visible(el)) continue;   // icon glyphs are not text a reader reads
+    measure(el, text);
+  }
+  for (const el of document.querySelectorAll('input:not([type=checkbox]):not([type=radio]):not([type=range]):not([type=hidden]):not([type=color]),textarea,select')) {
+    if (el.disabled || el.closest(EXEMPT) || !visible(el)) continue;
+    const text = String(el.value || '').trim();
+    if (text) measure(el, text);
+  }
+  if (dark) {
+    const area = window.innerWidth * window.innerHeight, flagged = [];
+    for (const el of document.querySelectorAll('body *')) {
+      if (el.closest('img,svg,video,canvas,picture,iframe') || flagged.some((f) => f.contains(el)) || !visible(el)) continue;
+      const c = parse(getComputedStyle(el).backgroundColor);
+      if (!c || c[3] < 0.5) continue;
+      const r = el.getBoundingClientRect();
+      const shown = Math.max(0, Math.min(r.right, window.innerWidth) - Math.max(r.left, 0)) * Math.max(0, Math.min(r.bottom, window.innerHeight) - Math.max(r.top, 0));
+      if (shown / area > 0.02 && lum(c) > 0.8) { flagged.push(el); light.push({ bg: rgb(c), share: Math.round(shown / area * 100), where: where(el), text: (el.innerText || '').trim().replace(/\s+/g, ' ').slice(0, 40) }); }
+    }
+  }
+  low.sort((a, b) => a.ratio - b.ratio);
+  return { low: low.slice(0, cap), light: light.slice(0, cap), low_n: low.length, light_n: light.length };
+};
+export const audit = (page, dark, min = 3.0, cap = 5) => page.evaluate(AUDIT, { dark, min, cap }).catch(() => null);

package/.tfcore/utils/tf-triage.py

@@ -13,8 +13,10 @@ row in whichever docs/<App>-Checklist.md or docs/<App>-P<N>-Checklist.md holds i
 
 demote  the row goes to Needs re-verify (% capped at 75) with a dated Remark holding the symptom in the
         reporter's words, the evidence path and the kind.
-new     a defect no row covers: the next free id in the prefix, a Not Started row, a detail entry with the
-        acceptance line and the marker BRD-pending (*amend-docs gives it its BRD item).
+new     a defect no row covers: the next free id in the prefix, across every checklist of the app and the
+        telemetry streams, a Not Started row, a detail entry with the acceptance line and the marker
+        BRD-pending (*amend-docs gives it its BRD item). Without --prefix: FN, or the one prefix a
+        checklist with no FN row uses; with several such prefixes it asks for --prefix.
 note    a dated remark on the nearest row, no status change (could not reproduce).
 close   what triage owes the telemetry, from the actions above (tests/.artifacts/verify/triage.json):
         one gate record per demoted or new row with gate "escaped" (no check caught it), one miss per row
@@ -31,6 +33,7 @@ import datetime
 import importlib.util
 import json
 import os
+import re
 import subprocess
 import sys
 
@@ -62,6 +65,17 @@ def cfg_phase():
     return 1
 
 
+def cfg_project_type():
+    """metrics.project_type from core-config.yaml: a library or docs project has no mockups."""
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(p):
+        import re
+        m = re.search(r"(?m)^\s+project_type:\s*(\S+)", open(p, encoding="utf-8").read())
+        if m:
+            return m.group(1).strip("'\"").lower()
+    return "app"
+
+
 def phase_checklist(app, ph):
     return os.path.join("docs", f"{app}-Checklist.md" if ph <= 1 else f"{app}-P{ph}-Checklist.md")
 
@@ -165,9 +179,21 @@ def main(argv):
             die("new needs \"<title>\" \"<acceptance>\"")
         title, acc = argv[3], argv[4]
         cl = checklist(app, argv, ce)
-        prefix = opt(argv, "--prefix", "FN").upper(); section = opt(argv, "--section"); ev = opt(argv, "--evidence")
+        prefix = opt(argv, "--prefix")
+        if prefix is None:
+            # FN unless this checklist has no FN row: then the one prefix it uses is the default, and
+            # several are asked for (TechieRag TF-005: phase 3 is all RAG, and FN was a slip)
+            used = sorted(set(re.findall(r"(?m)^\|\s*REQ-([A-Z]+)-\d{3,}", ce.read(cl))))
+            if not used or "FN" in used:
+                prefix = "FN"
+            elif len(used) == 1:
+                prefix = used[0]
+                print(f"note: every row of {cl} is REQ-{prefix}-…, so the new row is one too; pass --prefix to choose another")
+            else:
+                die(f"{cl} has no REQ-FN rows; name the prefix: --prefix {'|'.join(used)}")
+        prefix = prefix.upper(); section = opt(argv, "--section"); ev = opt(argv, "--evidence")
         src = opt(argv, "--source", "owner"); mockup = opt(argv, "--mockup")
-        if prefix == "UI" and not mockup:
+        if prefix == "UI" and not mockup and cfg_project_type() not in ("library", "docs"):   # TrBlazeUI TF-003
             print("note: a UI row needs a mockup link; pass --mockup docs/mockups/<screen>.html or the checker will flag it")
         rid = ce.add_row(cl, prefix, title, acc, section=section, mockup=mockup,
                          remark=f"logged from {'production' if src == 'production' else 'UAT'} {ce.TODAY}" + (f" (evidence: {ev})" if ev else ""))