@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/utils/tf-verify-boot.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# tf-verify-boot.sh — start the application for a verify, reach it, and stop it (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-verify-boot.sh start [--head web|windows|static] [--project <csproj>]
+#                                              [--port N] [--config Release] [--static <dir>]
+#   bash .tfcore/utils/tf-verify-boot.sh stop
+#   bash .tfcore/utils/tf-verify-boot.sh status
+#
+# Heads:
+#   web      a project on Microsoft.NET.Sdk.Web: started with `dotnet run --urls`, first through
+#            the rungs tf-build.sh knows (dotnet, ~/.dotnet/dotnet, then Windows-side cmd.exe on
+#            WSL), polled until it answers. Prints BOOTED mode=base url=http://localhost:PORT.
+#   windows  a MAUI Blazor Hybrid head (UseMaui + a net*-windows target): started Windows-side with
+#            WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222, the DevTools port
+#            relayed to every interface by tf-cdp-relay.ps1, and reached from WSL over CDP. Prints
+#            BOOTED mode=cdp url=http://<host>:9223. Proven on MyDiary, 2026-09-06.
+#   static   a folder of HTML served by python3 (the framework self-test, a mockup set).
+#   android, ios, maccatalyst: no driver ships in this framework version. NONE with that reason;
+#            their rows are recorded as not verified, never as static-only passes.
+# Without --head the script picks web when a web project exists, else windows when a MAUI project
+# with a windows target exists, else NONE. --project names the project when there are several.
+# The state goes to tests/.artifacts/verify/boot.json; the app log to tests/.artifacts/verify/app.log.
+# `stop` kills what `start` started and nothing else. Never asks anyone to start anything.
+# Exit 0 booted / stopped · 2 NONE (reason printed; kind=build-error, host or no-driver) · 3 usage.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DIR="tests/.artifacts/verify"; STATE="$DIR/boot.json"; LOG="$DIR/app.log"
+mkdir -p "$DIR"
+
+PLATFORM="linux"
+U="$(uname -s 2>/dev/null || echo windows)"
+if [[ "$U" == Darwin* ]]; then PLATFORM="macos"
+elif [[ "$U" == Linux* ]]; then grep -qiE "microsoft|wsl" /proc/version 2>/dev/null && PLATFORM="wsl"
+else PLATFORM="windows"; fi
+
+winarg() { # a Windows path as a cmd.exe argument: bare when it has no space (a quote passed
+  # through the WSL bridge reaches dotnet as part of the path: "does not exist: \"C:\...\""; miss 23)
+  if [[ "$1" == *" "* ]]; then printf '"%s"' "$1"; else printf '%s' "$1"; fi; }
+json_escape() { python3 -c 'import json,sys; print(json.dumps(sys.argv[1]))' "$1"; }
+
+write_state() { # head mode url pids rung project reason kind
+  python3 - "$@" <<'PY'
+import json, sys, datetime
+head, mode, url, pids, rung, project, reason, kind = sys.argv[1:9]
+json.dump({"head": head, "mode": mode, "url": url, "pids": [int(p) for p in pids.split() if p.isdigit()],
+           "rung": rung, "project": project, "reason": reason, "reason_kind": kind, "stopped": False,
+           "platform": sys.argv[9] if len(sys.argv) > 9 else "", "log": "tests/.artifacts/verify/app.log",
+           "started": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")},
+          open("tests/.artifacts/verify/boot.json", "w"), indent=1)
+PY
+}
+
+find_projects() { # prints csproj paths under src/, source/, the root and one level down; never tests
+  find . -maxdepth 4 -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*' -not -path '*/node_modules/*' \
+       -not -path './tests/*' -not -path '*/test/*' -not -path '*Tests/*' -not -path '*.Tests/*' 2>/dev/null | sed 's#^\./##' | sort
+}
+is_web()  { grep -qE 'Microsoft\.NET\.Sdk\.Web|Microsoft\.NET\.Sdk\.BlazorWebAssembly' "$1"; }
+is_maui_win() { grep -qiE '<UseMaui>\s*true|Microsoft\.NET\.Sdk\.Maui' "$1" && grep -qE 'net[0-9.]+-windows' "$1"; }
+
+poll_http() { # url seconds pid-to-watch(optional) -> 0 when it answers
+  local url="$1" secs="$2" pid="${3:-}" i=0 code
+  while [[ $i -lt $secs ]]; do
+    code="$(curl -s -o /dev/null -m 3 -w '%{http_code}' "$url" 2>/dev/null || true)"
+    [[ "$code" =~ ^[23] ]] && return 0
+    if [[ -n "$pid" ]] && ! kill -0 "$pid" 2>/dev/null; then return 1; fi
+    sleep 2; i=$((i+2))
+  done
+  return 1
+}
+WRONG_RUNG='NETSDK1178|Microsoft\.(iOS|Android|MacCatalyst|tvOS)\.Sdk|Workload ID|WindowsAppSDK|command not found|No such file or directory|workload.*not installed'
+CODE_ERR='error (CS|RZ|BL|XC|XLS)[0-9]{3,5}|error MSB[0-9]{4}: .*(does not exist|could not be found)|error NU1'
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  status) if [[ -f "$STATE" ]]; then cat "$STATE"; else echo "NONE no boot state"; fi; exit 0 ;;
+  stop)
+    [[ -f "$STATE" ]] || { echo "STOPPED nothing was started"; exit 0; }
+    python3 - <<'PY'
+import json, os, signal, subprocess, time
+s = json.load(open("tests/.artifacts/verify/boot.json"))
+for pid in s.get("pids", []):
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        try:
+            subprocess.run(["pkill", "-" + sig.name.replace("SIG", ""), "-P", str(pid)], capture_output=True)
+            os.kill(pid, sig)
+        except ProcessLookupError:
+            break
+        except Exception:
+            pass
+        time.sleep(1)
+image = s.get("win_image") or ""
+if image:
+    subprocess.run(["taskkill.exe", "/F", "/T", "/IM", image], capture_output=True)
+if s.get("win_port"):
+    ps = f"Get-NetTCPConnection -LocalPort {s['win_port']} -State Listen -ErrorAction SilentlyContinue | ForEach-Object {{ Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }}"
+    subprocess.run(["powershell.exe", "-NoProfile", "-Command", ps], capture_output=True)
+s["stopped"] = True
+json.dump(s, open("tests/.artifacts/verify/boot.json", "w"), indent=1)
+print(f"STOPPED head={s.get('head')} mode={s.get('mode')} pids={s.get('pids')}")
+PY
+    exit 0 ;;
+  start) ;;
+  *) sed -n '2,26p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 3 ;;
+esac
+
+HEAD=""; PROJECT=""; PORT=""; CONFIG=""; STATIC=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --head) HEAD="${2:-}"; shift 2 ;;
+    --project) PROJECT="${2:-}"; shift 2 ;;
+    --port) PORT="${2:-}"; shift 2 ;;
+    --config) CONFIG="${2:-}"; shift 2 ;;
+    --static) STATIC="${2:-}"; HEAD="static"; shift 2 ;;
+    *) echo "tf-verify-boot: unknown argument $1" >&2; exit 3 ;;
+  esac
+done
+: > "$LOG"
+
+# ---- static ---------------------------------------------------------------------------
+if [[ "$HEAD" == "static" ]]; then
+  [[ -d "$STATIC" ]] || { echo "NONE head=static reason=folder $STATIC does not exist"; write_state static none "" "" "" "$STATIC" "folder missing" host; exit 2; }
+  PORT="${PORT:-5099}"
+  if curl -s -o /dev/null -m 2 "http://localhost:$PORT/" 2>/dev/null; then
+    echo "NONE head=static reason=port $PORT is already in use; stop that process or pass --port"; exit 2
+  fi
+  nohup python3 -m http.server "$PORT" --directory "$STATIC" --bind 127.0.0.1 > "$LOG" 2>&1 &
+  PID=$!
+  if poll_http "http://localhost:$PORT/" 20 "$PID"; then
+    write_state static base "http://localhost:$PORT" "$PID" "python3 http.server" "$STATIC" "" "" "$PLATFORM"
+    echo "BOOTED head=static mode=base url=http://localhost:$PORT pid=$PID log=$LOG"; exit 0
+  fi
+  kill "$PID" 2>/dev/null; write_state static none "" "" "" "$STATIC" "http.server did not answer on $PORT" host
+  echo "NONE head=static reason=http.server did not answer on $PORT (log $LOG)"; exit 2
+fi
+
+# ---- pick the project and the head ------------------------------------------------------
+mapfile -t ALL < <(find_projects)
+WEB=(); WIN=()
+for p in "${ALL[@]}"; do is_web "$p" && WEB+=("$p"); is_maui_win "$p" && WIN+=("$p"); done
+if [[ -n "$PROJECT" ]]; then
+  [[ -f "$PROJECT" ]] || { echo "NONE reason=--project $PROJECT does not exist"; exit 3; }
+  if [[ -z "$HEAD" ]]; then is_web "$PROJECT" && HEAD=web; [[ -z "$HEAD" ]] && is_maui_win "$PROJECT" && HEAD=windows; fi
+elif [[ -z "$HEAD" ]]; then
+  if [[ ${#WEB[@]} -gt 0 ]]; then HEAD=web; PROJECT="${WEB[0]}"
+  elif [[ ${#WIN[@]} -gt 0 ]]; then HEAD=windows; PROJECT="${WIN[0]}"; fi
+else
+  case "$HEAD" in web) PROJECT="${WEB[0]:-}" ;; windows) PROJECT="${WIN[0]:-}" ;; esac
+fi
+case "$HEAD" in
+  android|ios|maccatalyst)
+    write_state "$HEAD" none "" "" "" "${PROJECT:-}" "no driver for the $HEAD head ships in this framework version" no-driver "$PLATFORM"
+    echo "NONE head=$HEAD reason=no driver for the $HEAD head ships in this framework version; its rows are recorded as not verified"; exit 2 ;;
+  web|windows) ;;
+  "") write_state none none "" "" "" "" "no web project and no MAUI project with a windows target found under src/, source/ or the root" host "$PLATFORM"
+      echo "NONE head=none reason=no web project (Microsoft.NET.Sdk.Web) and no MAUI project with a windows target found; name one with --project"; exit 2 ;;
+  *) echo "NONE reason=unknown head $HEAD"; exit 3 ;;
+esac
+[[ -n "$PROJECT" ]] || { write_state "$HEAD" none "" "" "" "" "no project for head $HEAD" host "$PLATFORM"; echo "NONE head=$HEAD reason=no project found for that head; name one with --project"; exit 2; }
+PDIR="$(dirname "$PROJECT")"; PNAME="$(basename "$PROJECT" .csproj)"
+ASM="$(grep -oE '<AssemblyName>[^<]+' "$PROJECT" 2>/dev/null | head -1 | sed 's/<AssemblyName>//')"; ASM="${ASM:-$PNAME}"
+CFGARGS=(); [[ -n "$CONFIG" ]] && CFGARGS=(-c "$CONFIG")
+
+# ---- web ------------------------------------------------------------------------------
+if [[ "$HEAD" == "web" ]]; then
+  if [[ -z "$PORT" ]]; then
+    LS="$PDIR/Properties/launchSettings.json"
+    [[ -f "$LS" ]] && PORT="$(grep -oE 'http://localhost:[0-9]+' "$LS" | head -1 | sed 's#.*:##')"
+    PORT="${PORT:-5099}"
+  fi
+  if curl -s -o /dev/null -m 2 "http://localhost:$PORT/" 2>/dev/null; then
+    echo "NONE head=web reason=port $PORT is already in use; stop that process or pass --port"; exit 2
+  fi
+  URL="http://localhost:$PORT"
+  rungs=()
+  case "$PLATFORM" in
+    wsl) command -v dotnet >/dev/null 2>&1 && rungs+=("dotnet"); [[ -x "$HOME/.dotnet/dotnet" ]] && rungs+=("$HOME/.dotnet/dotnet"); command -v cmd.exe >/dev/null 2>&1 && rungs+=("cmd.exe") ;;
+    *) rungs+=("dotnet") ;;
+  esac
+  [[ ${#rungs[@]} -gt 0 ]] || { write_state web none "" "" "" "$PROJECT" "no dotnet on this host" host "$PLATFORM"; echo "NONE head=web reason=no dotnet found on $PLATFORM"; exit 2; }
+  tried=()
+  for r in "${rungs[@]}"; do
+    echo "### rung: $r" >> "$LOG"
+    case "$r" in
+      cmd.exe)
+        WP="$(winarg "$(wslpath -w "$PROJECT")")"
+        nohup cmd.exe /c "dotnet run --project $WP ${CFGARGS[*]} --urls $URL" >> "$LOG" 2>&1 < /dev/null &
+        PID=$!; label="cmd.exe /c dotnet" ;;
+      *)
+        ASPNETCORE_ENVIRONMENT="${ASPNETCORE_ENVIRONMENT:-Development}" nohup "$r" run --project "$PROJECT" "${CFGARGS[@]}" --urls "$URL" >> "$LOG" 2>&1 < /dev/null &
+        PID=$!; label="$r" ;;
+    esac
+    tried+=("$label")
+    if poll_http "$URL/" 120 "$PID"; then
+      WP_PORT=""; [[ "$r" == "cmd.exe" ]] && WP_PORT="$PORT"
+      write_state web base "$URL" "$PID" "$label" "$PROJECT" "" "" "$PLATFORM"
+      [[ -n "$WP_PORT" ]] && python3 -c "import json;p='$STATE';s=json.load(open(p));s['win_port']=$WP_PORT;json.dump(s,open(p,'w'),indent=1)"
+      echo "BOOTED head=web mode=base url=$URL rung=$label project=$PROJECT pid=$PID log=$LOG"; exit 0
+    fi
+    pkill -P "$PID" 2>/dev/null; kill "$PID" 2>/dev/null
+    seg="$(awk '/^### rung: /{p=0} index($0,"### rung: '"$r"'")==1{p=1} p' "$LOG")"
+    if grep -qE "$CODE_ERR" <<<"$seg" && ! grep -qE "$WRONG_RUNG" <<<"$seg"; then
+      first="$(grep -E 'error (CS|RZ|BL|XC|XLS|MSB|NU)[0-9]+' <<<"$seg" | head -1 | sed 's/^\s*//' | cut -c1-160)"
+      write_state web none "" "" "$label" "$PROJECT" "build error: $first" build-error "$PLATFORM"
+      echo "NONE head=web kind=build-error reason=the code does not build via $label: $first (log $LOG)"; exit 2
+    fi
+  done
+  write_state web none "" "" "" "$PROJECT" "no rung answered on $URL; tried ${tried[*]}" host "$PLATFORM"
+  echo "NONE head=web kind=host reason=no rung brought $PROJECT up on $URL within 120 s; tried: ${tried[*]} (log $LOG)"; exit 2
+fi
+
+# ---- windows (MAUI Blazor Hybrid over CDP) --------------------------------------------------
+[[ "$PLATFORM" == "wsl" || "$PLATFORM" == "windows" ]] || { write_state windows none "" "" "" "$PROJECT" "a Windows head runs only from WSL or Windows" host "$PLATFORM"; echo "NONE head=windows reason=a Windows head runs only from WSL or Windows, this is $PLATFORM"; exit 2; }
+command -v cmd.exe >/dev/null 2>&1 || { write_state windows none "" "" "" "$PROJECT" "cmd.exe not reachable" host "$PLATFORM"; echo "NONE head=windows reason=cmd.exe is not reachable from this shell"; exit 2; }
+TFM="$(grep -oE 'net[0-9.]+-windows[0-9.]*' "$PROJECT" | head -1)"
+CDP_PORT=9222; RELAY_PORT="${PORT:-9223}"
+WP="$(winarg "$(wslpath -w "$PROJECT")")"; RELAY="$(wslpath -w "$HERE/tf-cdp-relay.ps1")"
+echo "### windows head: $PROJECT -f $TFM" >> "$LOG"
+nohup cmd.exe /c "set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=$CDP_PORT&& dotnet run --project $WP -f $TFM ${CFGARGS[*]}" >> "$LOG" 2>&1 < /dev/null &
+APP_PID=$!
+nohup powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$RELAY" -ListenPort "$RELAY_PORT" -TargetPort "$CDP_PORT" >> "$DIR/relay.log" 2>&1 < /dev/null &
+RELAY_PID=$!
+GW="$(ip route 2>/dev/null | awk '/default/{print $3; exit}')"
+HOSTS=("localhost"); [[ -n "$GW" ]] && HOSTS+=("$GW")
+i=0; URL=""
+while [[ $i -lt 300 && -z "$URL" ]]; do
+  for h in "${HOSTS[@]}"; do
+    if curl -s -m 2 "http://$h:$RELAY_PORT/json/version" 2>/dev/null | grep -q '"webSocketDebuggerUrl"'; then URL="http://$h:$RELAY_PORT"; break; fi
+  done
+  [[ -n "$URL" ]] && break
+  if ! kill -0 "$APP_PID" 2>/dev/null; then
+    seg="$(cat "$LOG")"
+    if grep -qE "$CODE_ERR" <<<"$seg"; then
+      first="$(grep -E 'error (CS|RZ|BL|XC|XLS|MSB|NU)[0-9]+' <<<"$seg" | head -1 | sed 's/^\s*//' | cut -c1-160)"
+      kill "$RELAY_PID" 2>/dev/null
+      write_state windows none "" "" "cmd.exe /c dotnet run -f $TFM" "$PROJECT" "build error: $first" build-error "$PLATFORM"
+      echo "NONE head=windows kind=build-error reason=the code does not build: $first (log $LOG)"; exit 2
+    fi
+  fi
+  sleep 3; i=$((i+3))
+done
+if [[ -z "$URL" ]]; then
+  pkill -P "$APP_PID" 2>/dev/null; kill "$APP_PID" "$RELAY_PID" 2>/dev/null
+  taskkill.exe /F /T /IM "$ASM.exe" >/dev/null 2>&1
+  write_state windows none "" "" "cmd.exe /c dotnet run -f $TFM" "$PROJECT" "the DevTools port $RELAY_PORT never answered within 300 s" host "$PLATFORM"
+  echo "NONE head=windows kind=host reason=the app's DevTools port never answered on ${HOSTS[*]}:$RELAY_PORT within 300 s (log $LOG, relay $DIR/relay.log)"; exit 2
+fi
+write_state windows cdp "$URL" "$APP_PID $RELAY_PID" "cmd.exe /c dotnet run -f $TFM" "$PROJECT" "" "" "$PLATFORM"
+python3 -c "import json;p='$STATE';s=json.load(open(p));s['win_image']='$ASM.exe';json.dump(s,open(p,'w'),indent=1)"
+echo "BOOTED head=windows mode=cdp url=$URL project=$PROJECT tfm=$TFM pids=$APP_PID,$RELAY_PID image=$ASM.exe log=$LOG"
+exit 0

package/.tfcore/utils/tf-verify-emit.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# tf-verify-emit.sh — the telemetry of a verify run, from its verdict file (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-verify-emit.sh <App> [--dir tests/.artifacts/verify] [--mode <mode>] [--started <ISO>]
+#
+# Reads <dir>/verdicts.json (written by tf-verify-verdict.sh) and appends, through tf-emit.sh only:
+#   gates.jsonl   one record per row that passed or failed a check: the first failing check (or null),
+#                 the checks that ran, the failure class, the prior status, the attempt number
+#   misses.jsonl  one `miss` per failing row that has no open miss of the same class (the duplicate
+#                 check is tf-emit.sh --open-miss); origin = the last build or fix run that touched
+#                 the row, looked up in runs.jsonl, or left out when there is none
+#   runs.jsonl    one `run` record for the verify pass: cmd verify-phase, the rows touched, the build
+#                 result, whether YOLO was on
+# Rows the run could not grade (not tested, not observable, not driven) get no record. Telemetry
+# never blocks: a refused record is printed and the script still exits 0.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+[[ $# -ge 1 && "$1" != "-h" && "$1" != "--help" ]] || { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 3; }
+APP="$1"; shift
+DIR="tests/.artifacts/verify"; MODE=""; STARTED=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) DIR="${2:-}"; shift 2 ;;
+    --mode) MODE="${2:-}"; shift 2 ;;
+    --started) STARTED="${2:-}"; shift 2 ;;
+    *) echo "tf-verify-emit: unknown argument $1" >&2; exit 3 ;;
+  esac
+done
+[[ -f "$DIR/verdicts.json" ]] || { echo "tf-verify-emit: $DIR/verdicts.json missing; run tf-verify-verdict.sh first" >&2; exit 2; }
+YOLO=false; bash "$HERE/tf-yolo.sh" is-on >/dev/null 2>&1 && YOLO=true
+[[ -z "$STARTED" ]] && STARTED="$(bash "$HERE/tf-phase.sh" show 2>/dev/null | sed -n 's/.*"started":"\([^"]*\)".*/\1/p')"
+
+TF_APP="$APP" TF_DIR="$DIR" TF_MODE="$MODE" TF_STARTED="$STARTED" TF_YOLO="$YOLO" TF_EMIT="$HERE/tf-emit.sh" python3 - <<'PY'
+import datetime, json, os, subprocess
+
+EMIT = os.environ["TF_EMIT"]; app = os.environ["TF_APP"]; d = os.environ["TF_DIR"]
+mode = os.environ["TF_MODE"] or None; started = os.environ["TF_STARTED"]; yolo = os.environ["TF_YOLO"] == "true"
+v = json.load(open(os.path.join(d, "verdicts.json"), encoding="utf-8"))
+run_id = started or v.get("started") or ""
+now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+def emit(stream, rec):
+    p = subprocess.run(["bash", EMIT, stream], input=json.dumps(rec), capture_output=True, text=True)
+    msg = (p.stdout + p.stderr).strip()
+    if p.returncode != 0 or "refus" in msg.lower() or "error" in msg.lower():
+        print(f"  {stream}: not written — {msg.splitlines()[0][:160] if msg else 'no reason printed'}")
+        return False
+    return True
+
+def q(*args):
+    p = subprocess.run(["bash", EMIT, *args], capture_output=True, text=True)
+    return p.stdout.strip()
+
+# origin lookup: the last build-phase or fix-issues run that touched the row
+runs_path = os.path.join(q("--where") or "docs/metrics", "runs.jsonl")
+origin = {}
+if os.path.isfile(runs_path):
+    for line in open(runs_path, encoding="utf-8", errors="replace"):
+        try:
+            r = json.loads(line)
+        except Exception:
+            continue
+        if r.get("kind") != "run" or r.get("backfilled") or r.get("cmd") not in ("build-phase", "fix-issues"):
+            continue
+        for rid in r.get("reqs_touched") or []:
+            if r.get("started", "") >= origin.get(rid, ("", ""))[0]:
+                origin[rid] = (r.get("started", ""), r.get("cmd"), (r.get("subagents") or ["flow-master"])[0] if r.get("subagents") else "flow-master")
+
+gates = misses = 0
+for row in v["rows"]:
+    if not row.get("emit_gate"):
+        continue
+    rid = row["id"]
+    att = q("--next-attempt", rid) or "1"
+    rec = {"kind": "gate", "app": app, "run_id": run_id, "req_id": rid, "req_class": row["class"],
+           "attempt": int(att) if att.isdigit() else 1, "verdict": row["status"], "gate": row["gate"],
+           "gates_run": row["gates_run"], "failure_class": row["failure_class"], "prior_verdict": row["prior_verdict"]}
+    if emit("gates", rec):
+        gates += 1
+    if not row["gate"]:
+        continue
+    cls = ("regression" if (row["prior_verdict"] or "").lower().startswith("verified")
+           else "standards-violation" if row["gate"] == "standards"
+           else "partial-implementation")
+    opened = q("--open-miss", rid)
+    if opened and opened.split()[-1] == cls:
+        continue
+    mid = q("--next-miss-id")
+    if not mid:
+        print(f"  misses: no id for {rid}; skipped")
+        continue
+    m = {"kind": "miss", "miss_id": mid, "req_id": rid, "req_class": row["class"], "miss_class": cls,
+         "artifact": "src", "severity": "major", "origin_phase": "build-phase", "origin_agent": "flow-master",
+         "found_by": "gate", "found_phase": "verify-phase", "found_gate": row["gate"], "found_run_id": run_id,
+         "failure_class": row["failure_class"] or "other"}
+    if rid in origin:
+        m["origin_run_id"], m["origin_phase"], m["origin_agent"] = origin[rid]
+    if emit("misses", m):
+        misses += 1
+
+touched = [r["id"] for r in v["rows"] if r.get("emit_gate")]
+rec = {"kind": "run", "app": app, "cmd": "verify-phase", "mode": mode, "yolo": yolo, "ended": now,
+       "reqs_touched": touched, "reqs_count": len(touched), "subagents": [], "files_written": 2,
+       "build_result": v.get("build_result", "not-run")}
+if run_id:
+    rec["started"] = run_id
+ok = emit("runs", rec)
+print(f"telemetry: {gates} gate record(s), {misses} new miss(es), run record {'written' if ok else 'not written'} (cmd verify-phase, yolo {str(yolo).lower()})")
+PY
+exit 0

package/.tfcore/utils/tf-verify-env.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# tf-verify-env.sh — make sure the browser tooling for a verify is present (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-verify-env.sh [--check]
+#
+# Ensures, in the current project: package.json; the playwright and @playwright/test packages;
+# the Chromium browser; playwright.config.ts with its output pinned under tests/.artifacts/;
+# the .gitignore lines for everything this tooling generates. --check reports and changes nothing.
+# Prints one line per item and READY at the end, or NOT-READY with the one command the owner
+# must run once (only when a browser install needs sudo and sudo is unavailable).
+# Exit 0 ready · 1 not ready · 2 node or npm missing.
+set -u
+CHECK=0; [[ "${1:-}" == "--check" ]] && CHECK=1
+command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 || { echo "NOT-READY node and npm are required"; exit 2; }
+ok=1
+
+say() { echo "  $*"; }
+
+# package.json
+if [[ ! -f package.json ]]; then
+  if [[ $CHECK -eq 1 ]]; then say "package.json: missing"; ok=0; else npm init -y >/dev/null 2>&1 && say "package.json: created"; fi
+else say "package.json: present"; fi
+
+# packages
+need=()
+node -e "require.resolve('playwright')" >/dev/null 2>&1 || need+=("playwright")
+node -e "require.resolve('@playwright/test')" >/dev/null 2>&1 || need+=("@playwright/test")
+if [[ ${#need[@]} -gt 0 ]]; then
+  if [[ $CHECK -eq 1 ]]; then say "packages: missing ${need[*]}"; ok=0
+  else say "packages: installing ${need[*]}"; npm install -D "${need[@]}" >/dev/null 2>&1 || { say "packages: npm install failed"; ok=0; }; fi
+else say "packages: playwright and @playwright/test present"; fi
+
+# browser
+if node -e "const {chromium}=require('playwright'); const p=chromium.executablePath(); require('fs').existsSync(p)?process.exit(0):process.exit(1)" >/dev/null 2>&1; then
+  say "chromium: present"
+else
+  if [[ $CHECK -eq 1 ]]; then say "chromium: missing"; ok=0
+  else
+    say "chromium: installing"
+    if ! npx playwright install chromium >/dev/null 2>&1; then
+      if ! npx playwright install --with-deps chromium >/dev/null 2>&1; then
+        if command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null; then
+          sudo npx playwright install --with-deps chromium >/dev/null 2>&1 || { say "chromium: install failed even with sudo"; ok=0; }
+        else
+          say "chromium: needs system libraries; run once: sudo npx playwright install --with-deps chromium"; ok=0
+        fi
+      fi
+    fi
+  fi
+fi
+
+# playwright.config.ts
+CFG='import { defineConfig } from '"'"'@playwright/test'"'"';
+export default defineConfig({
+  testDir: '"'"'./tests/verify'"'"',
+  outputDir: '"'"'./tests/.artifacts/test-results'"'"',
+  reporter: '"'"'line'"'"',
+  use: { headless: true, screenshot: '"'"'only-on-failure'"'"', trace: '"'"'retain-on-failure'"'"' },
+});'
+if [[ ! -f playwright.config.ts ]]; then
+  if [[ $CHECK -eq 1 ]]; then say "playwright.config.ts: missing"; ok=0; else printf '%s\n' "$CFG" > playwright.config.ts; say "playwright.config.ts: written"; fi
+elif ! grep -q "tests/.artifacts" playwright.config.ts; then
+  if [[ $CHECK -eq 1 ]]; then say "playwright.config.ts: outputDir not under tests/.artifacts"; ok=0
+  else
+    if grep -q "outputDir" playwright.config.ts; then
+      sed -i "s#outputDir:[^,]*,#outputDir: './tests/.artifacts/test-results',#" playwright.config.ts
+    else
+      sed -i "s#defineConfig({#defineConfig({\n  outputDir: './tests/.artifacts/test-results',#" playwright.config.ts
+    fi
+    say "playwright.config.ts: outputDir pinned under tests/.artifacts"
+  fi
+else say "playwright.config.ts: present, output pinned"; fi
+
+# .gitignore
+missing=()
+for line in "node_modules/" "tests/.artifacts/" "test-results/" "playwright-report/" "/docs/.last-verify.json" ".verify/"; do
+  grep -qsF -- "$line" .gitignore || missing+=("$line")
+done
+if [[ ${#missing[@]} -gt 0 ]]; then
+  if [[ $CHECK -eq 1 ]]; then say ".gitignore: missing ${missing[*]}"; ok=0
+  else
+    { [[ -f .gitignore ]] && [[ -n "$(tail -c1 .gitignore)" ]] && echo; echo "# TechieFlow agent artifacts — machine-generated test harness & logs, never commit"; printf '%s\n' "${missing[@]}"; } >> .gitignore
+    say ".gitignore: added ${missing[*]}"
+  fi
+else say ".gitignore: complete"; fi
+
+mkdir -p tests/.artifacts/verify tests/verify 2>/dev/null
+if [[ $ok -eq 1 ]]; then echo "READY"; exit 0; else echo "NOT-READY"; exit 1; fi