@techierathore/techieflow 1.0.2 → 1.0.3

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""tf-build-list.py — the mechanical start of a build pass (see tf-build-list.sh).
+
+    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 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
+  - 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.
+Writes nothing. Python 3 standard library only. Exit 0 printed, 2 could not run.
+"""
+import os
+import re
+import sys
+
+TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+FIX = {"fail", "partial", "in progress", "needs re-verify"}
+BLOCKED = {"blocked"}
+BUILDER = {"UI": "trblazeui", "RAG": "techierag", "FN": "builder", "NFR": "builder"}
+TPL = os.path.join(".tfcore", "templates", "v4custom", "build-subagent-prompt.md")
+
+
+def die(msg):
+    print(f"tf-build-list: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def read(p):
+    with open(p, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def config_phase():
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(p):
+        m = re.search(r"(?m)^appPhase:\s*(\d+)", read(p))
+        if m:
+            return int(m.group(1))
+    return 1
+
+
+def norm(s):
+    s = s.strip().strip("`* ").lower()
+    return re.sub(r"\s*\(.*$", "", s).strip()
+
+
+def rows_of(text):
+    rows = []
+    for line in text.splitlines():
+        if re.match(r"^\s*\|\s*`?REQ-", line):
+            c = [x.strip() for x in line.strip().strip("|").split("|")]
+            if len(c) >= 3:
+                rows.append({"id": c[0].strip("`* "), "title": c[1].strip("`* "), "status": norm(c[2]),
+                             "remarks": c[4] if len(c) > 4 else ""})
+    return rows
+
+
+def entries_of(text):
+    """id -> (section heading, acceptance line, mockup, brd)"""
+    out, current = {}, "Other"
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        m = re.match(r"^##\s+(.+)$", line)
+        if m:
+            current = re.sub(r"^(?:page|screen)\s*:\s*", "", m.group(1).strip(), flags=re.I)
+            continue
+        a = re.search(r"<a id=['\"]d-(req-[a-z]+-\d+)['\"]", line, re.I)
+        if a:
+            rid = a.group(1).upper()
+            acc = mock = brd = ""
+            for j in range(i, min(i + 12, len(lines))):
+                l = lines[j]
+                if re.search(r"\*Acceptance:?\*|^\s*[-*]\s*Acceptance:", l, re.I) and not acc:
+                    acc = re.sub(r"^\s*[-*]\s*\*?Acceptance:?\*?:?\s*", "", l).strip()
+                mm = re.search(r"((?:docs/)?mockups/[\w./-]+\.html)", l)
+                if mm and not mock:
+                    mock = mm.group(1)
+                bm = re.search(r"BRD-\d+", l)
+                if bm and not brd:
+                    brd = bm.group(0)
+                if j > i and re.match(r"^\s*(?:[-*]\s*)?<a id=|^## ", l):
+                    break   # the next entry starts (it begins with "- <a id="): nothing below is this row's
+            out[rid] = (current, acc, mock, brd)
+    return out
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    app = argv[1]
+    prompts = "--prompts" in argv
+    phase = config_phase()
+    if "--phase" in argv:
+        i = argv.index("--phase")
+        if i + 1 >= len(argv) or not argv[i + 1].isdigit():
+            die("--phase needs a number")
+        phase = int(argv[i + 1])
+    pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+    cl = os.path.join("docs", f"{pfx}Checklist.md")
+    if not os.path.isfile(cl):
+        die(f"{cl} does not exist; day-1 stage 2 writes it")
+    text = read(cl)
+    rows = rows_of(text)
+    if not rows:
+        die(f"{cl} has no REQ rows")
+    ent = entries_of(text)
+
+    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]
+    if fix_rows:
+        mode, work = "FIX", fix_rows
+    elif open_rows:
+        mode, work = "FRESH", open_rows
+    else:
+        mode, work = "NOTHING", []
+    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"
+          + (f" — {', '.join(r['id'] for r in work[:8])}{' …' if len(work) > 8 else ''}" if work else ""))
+    if blocked:
+        print("Blocked (library gaps, pass through unless the feedback entry is resolved): " + ", ".join(r["id"] for r in blocked))
+    if not work:
+        print("Nothing to build. Run the status gate; the next command is the verifier's or the owner's.")
+        return 0
+
+    clusters = {}
+    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])
+        clusters.setdefault(key, []).append((r, acc, mock, brd))
+    print()
+    print("## Clusters (one sub-agent each; spawn them all in one turn)")
+    letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    named = []
+    for i, ((sec, builder), items) in enumerate(clusters.items()):
+        label = letters[i % 26] + ("" if i < 26 else str(i // 26))
+        named.append((label, sec, builder, items))
+        mocks = sorted({m for _r, _a, m, _b in items if m})
+        print(f"Cluster {label} [{builder}]: " + ", ".join(r["id"] for r, *_ in items)
+              + f"  ({sec}" + (f" — mockup: {', '.join(mocks)}" if mocks else "") + ")")
+    print()
+    print("## Working list")
+    for label, sec, builder, items in named:
+        for r, acc, mock, brd in items:
+            todo = "" if acc else "  ⚠ no acceptance line: fix the checklist first"
+            print(f"- {r['id']} [{label}/{builder}] {r['title']} — {r['status']}{todo}")
+            if acc:
+                print(f"    Acceptance: {acc}")
+            if mock:
+                print(f"    Mockup: {mock}")
+    if not prompts:
+        print()
+        print("Add --prompts for one ready sub-agent prompt per cluster.")
+        return 0
+    if not os.path.isfile(TPL):
+        die(f"template {TPL} does not exist at its literal path")
+    tpl = read(TPL)
+    tpl = re.sub(r"<!--.*?-->\s*", "", tpl, flags=re.S)
+    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'}")
+            if mock:
+                lines.append(f"  Mockup: {mock}")
+        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))
+        print()
+        print(f"## Prompt for cluster {label} [{builder}]")
+        print(body.strip())
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except Exception as e:
+        die(str(e))

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

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# tf-build-list.sh — the mechanical start of a build pass.
+#
+#   bash .tfcore/utils/tf-build-list.sh MyApp               # mode (FIX / FRESH / NOTHING), clusters, working list
+#   bash .tfcore/utils/tf-build-list.sh MyApp --prompts     # plus one ready sub-agent prompt per cluster
+#   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).
+# 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
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-build-list: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-build-list.py" "$@"

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# tf-build.sh — build, test or run a .NET target on whatever host this is, trying the
+# invocation rungs in order and stopping at the first that works (Sitting 4b, 2026-09-05;
+# replaces the prose ladder build-invocation-ladder.md §0 to §C).
+#
+#   bash .tfcore/utils/tf-build.sh [build] [<target>] [-- <extra dotnet args>]
+#   bash .tfcore/utils/tf-build.sh test  [<target>] [-- <extra dotnet args>]
+#   bash .tfcore/utils/tf-build.sh run   <project>  [-- <extra dotnet args>]
+#   bash .tfcore/utils/tf-build.sh probe                 # print the platform and the rungs, run nothing
+#
+# <target> is a .sln, .slnx or .csproj relative to the current folder (default: the one
+# solution or project found here). Output goes to tests/.artifacts/build/<UTC time>.log.
+#
+# Prints ONE verdict line the agent copies into the status log row:
+#   PASS  built on wsl via cmd.exe /c dotnet (rung 4) — 0 warnings
+#   FAIL  real compile errors on wsl via ~/.dotnet/dotnet (rung 2): 3 CS errors, first: …
+#   NOT-RUN no rung could run dotnet on wsl; tried: dotnet, ~/.dotnet/dotnet, cmd.exe, winrun, powershell.exe
+# Exit 0 PASS · 1 FAIL (the code is wrong: fix it) · 2 NOT-RUN (the host is wrong: never a
+# project blocker; say which rungs were tried).
+#
+# Rungs by host (docs/TechieFlow-How-It-Works.md; build-invocation-ladder.md §D keeps the
+# runtime-driver table, which this script does not replace):
+#   macOS / native Linux / native Windows:  dotnet
+#   WSL, no MAUI head in the target:        dotnet · ~/.dotnet/dotnet · winrun · cmd.exe /c dotnet · powershell.exe dotnet
+#   WSL, a MAUI head in the target:         cmd.exe /c dotnet · winrun · powershell.exe dotnet   (workloads live Windows-side)
+#   OpenCode Docker (TF_OPENCODE_DOCKER=1 or winrun + TF_WINDOWS_APP_PATH): MAUI → winrun; else dotnet
+# A workload / SDK-missing error (NETSDK1178, Microsoft.iOS/Android/MacCatalyst.Sdk, Workload ID,
+# WindowsAppSDK, command not found) means the wrong rung: the next one is tried, nothing is logged
+# as a blocker. A CS#### error means the code is wrong: the rung stays and the script exits 1.
+set -u
+
+MODE="build"; TARGET=""; EXTRA=()
+case "${1:-}" in
+  build|test|run|probe) MODE="$1"; shift ;;
+esac
+while [[ $# -gt 0 ]]; do
+  if [[ "$1" == "--" ]]; then shift; EXTRA=("$@"); break; fi
+  TARGET="$1"; shift
+done
+
+# ---- platform -------------------------------------------------------------------------
+PLATFORM="linux"
+U="$(uname -s 2>/dev/null || echo windows)"
+if [[ "$U" == Darwin* ]]; then PLATFORM="macos"
+elif [[ "$U" == Linux* ]]; then
+  if grep -qiE "microsoft|wsl" /proc/version 2>/dev/null; then PLATFORM="wsl"
+  elif [[ "${TF_OPENCODE_DOCKER:-}" == "1" ]] || { [[ -x /usr/local/bin/winrun ]] && [[ -n "${TF_WINDOWS_APP_PATH:-}" ]]; }; then PLATFORM="docker"
+  fi
+elif [[ "$U" == windows || "$U" == MINGW* || "$U" == MSYS* || "$U" == CYGWIN* ]]; then PLATFORM="windows"
+fi
+
+# ---- target ---------------------------------------------------------------------------
+if [[ -z "$TARGET" && "$MODE" != "probe" ]]; then
+  mapfile -t CANDS < <(ls -1 *.slnx *.sln 2>/dev/null; ls -1 *.csproj 2>/dev/null)
+  if [[ ${#CANDS[@]} -eq 1 ]]; then TARGET="${CANDS[0]}"
+  elif [[ ${#CANDS[@]} -gt 1 ]]; then echo "NOT-RUN more than one solution or project here; name one: ${CANDS[*]}"; exit 2
+  fi
+fi
+
+# ---- does the target include a MAUI head? ----------------------------------------------
+maui=0
+projects=()
+if [[ -n "$TARGET" ]]; then
+  case "$TARGET" in
+    *.csproj) projects=("$TARGET") ;;
+    *.sln)  mapfile -t projects < <(grep -oE '"[^"]+\.csproj"' "$TARGET" 2>/dev/null | tr -d '"' | tr '\\' '/') ;;
+    *.slnx) mapfile -t projects < <(grep -oE 'Path="[^"]+\.csproj"' "$TARGET" 2>/dev/null | sed 's/Path="//; s/"$//' | tr '\\' '/') ;;
+  esac
+  base="$(dirname "$TARGET")"
+  for p in "${projects[@]}"; do
+    f="$p"; [[ -f "$f" ]] || f="$base/$p"
+    [[ -f "$f" ]] || continue
+    if grep -qiE '<UseMaui>\s*true|Microsoft\.NET\.Sdk\.Maui|net[0-9.]+-(android|ios|maccatalyst|windows10)' "$f"; then maui=1; fi
+  done
+fi
+
+# ---- rungs -----------------------------------------------------------------------------
+rungs=()
+case "$PLATFORM" in
+  macos|linux|windows) rungs=("dotnet") ;;
+  docker) if [[ $maui -eq 1 ]]; then rungs=("winrun"); else rungs=("dotnet" "winrun"); fi ;;
+  wsl)
+    if [[ $maui -eq 1 ]]; then rungs=("cmd.exe" "winrun" "powershell.exe")
+    else rungs=("dotnet" "$HOME/.dotnet/dotnet" "winrun" "cmd.exe" "powershell.exe"); fi ;;
+esac
+
+if [[ "$MODE" == "probe" ]]; then
+  echo "platform: $PLATFORM · target: ${TARGET:-none} · maui head: $([[ $maui -eq 1 ]] && echo yes || echo no)"
+  echo "rungs, in order: ${rungs[*]}"
+  exit 0
+fi
+[[ -z "$TARGET" && "$MODE" != "run" ]] && { echo "NOT-RUN no .sln, .slnx or .csproj here; name the target"; exit 2; }
+
+# ---- the dotnet verb -------------------------------------------------------------------
+verb="$MODE"
+args=("$verb")
+[[ -n "$TARGET" ]] && args+=("$TARGET")
+[[ "$MODE" == "run" ]] && args=("run" "--project" "$TARGET")
+args+=("${EXTRA[@]}")
+
+mkdir -p tests/.artifacts/build
+LOG="tests/.artifacts/build/$(date -u +%Y%m%dT%H%M%SZ)-$MODE.log"
+WRONG_RUNG='NETSDK1178|Microsoft\.(iOS|Android|MacCatalyst|tvOS)\.Sdk|Workload ID|not recognized|WindowsAppSDK|command not found|No such file or directory|is not recognized as an internal or external command|The term .* is not recognized|workload.*not installed|Inadequate permissions'
+
+tried=()
+n=0
+for r in "${rungs[@]}"; do
+  n=$((n+1))
+  case "$r" in
+    dotnet)          cmd=(dotnet "${args[@]}"); label="dotnet" ;;
+    */.dotnet/dotnet) cmd=("$r" "${args[@]}"); label="~/.dotnet/dotnet" ;;
+    winrun)          cmd=(winrun "dotnet ${args[*]}"); label="winrun dotnet" ;;
+    cmd.exe)         cmd=(cmd.exe /c "dotnet ${args[*]}"); label="cmd.exe /c dotnet" ;;
+    powershell.exe)  cmd=(powershell.exe -Command "dotnet ${args[*]}"); label="powershell.exe dotnet" ;;
+  esac
+  tried+=("$label")
+  { echo "### rung $n: ${cmd[*]}"; "${cmd[@]}" 2>&1; echo "### exit $?"; } >> "$LOG" 2>&1
+  rc="$(tail -1 "$LOG" | sed 's/### exit //')"
+  seg="$(awk -v n="### rung $n:" 'index($0,n)==1{p=1} p' "$LOG")"
+  if [[ "$rc" == "0" ]]; then
+    warns="$(grep -cE 'warning [A-Z]+[0-9]+' <<<"$seg" || true)"
+    echo "PASS  $MODE on $PLATFORM via $label (rung $n) — $warns warning line(s); log $LOG"
+    exit 0
+  fi
+  # Code errors: C# (CS), Razor (RZ), Blazor (BL), XAML (XC, XLS), missing reference (MSB/NU).
+  # Until 2026-09-06 only CS counted, so a build failing on sixteen Razor RZ9991 errors was
+  # taken for a wrong rung and reported NOT-RUN "host issue" (MISS-TechieFlow-20260906-03).
+  if grep -qE 'error (CS|RZ|BL|XC|XLS)[0-9]{3,5}|error MSB[0-9]{4}: .*(does not exist|could not be found)|error NU1' <<<"$seg" && ! grep -qE "$WRONG_RUNG" <<<"$seg"; then
+    errs="$(grep -cE 'error (CS|RZ|BL|XC|XLS|MSB|NU)[0-9]+' <<<"$seg" || true)"
+    first="$(grep -E 'error (CS|RZ|BL|XC|XLS|MSB|NU)[0-9]+' <<<"$seg" | head -1 | sed 's/^\s*//' | cut -c1-160)"
+    echo "FAIL  real errors on $PLATFORM via $label (rung $n): $errs error line(s), first: $first; log $LOG"
+    grep -E 'error (CS|RZ|BL|XC|XLS|MSB|NU)[0-9]+' <<<"$seg" | sed 's/^\s*//' | sort -u | head -10
+    exit 1
+  fi
+  if [[ "$MODE" == "test" ]] && grep -qE 'Failed!|Failed:\s+[1-9]|Tests? failed' <<<"$seg"; then
+    echo "FAIL  tests failed on $PLATFORM via $label (rung $n); log $LOG"
+    grep -E 'Failed |Failed!|Error Message|Total tests|Passed!' <<<"$seg" | head -12
+    exit 1
+  fi
+  # anything else (workload, wrong rung, tool absent): try the next rung
+done
+echo "NOT-RUN no rung could $MODE on $PLATFORM; tried: ${tried[*]}. This is a host issue, never a project blocker; log $LOG"
+exit 2

package/.tfcore/utils/tf-cdp-relay.ps1

@@ -0,0 +1,64 @@
+# tf-cdp-relay.ps1 — relay a Windows loopback port to every interface (Sitting 4c, 2026-09-06).
+#
+#   powershell.exe -File tf-cdp-relay.ps1 -ListenPort 9223 -TargetPort 9222
+#
+# A MAUI Blazor Hybrid app's WebView2 opens its DevTools port on 127.0.0.1 only, so WSL cannot
+# reach it. This relay listens on every interface and forwards to the loopback port, so Playwright
+# in WSL can attach with connectOverCDP('http://<windows host ip>:9223'). Started and stopped by
+# tf-verify-boot.sh; proven on MyDiary's Windows head, 2026-09-06 (the DevGuide run).
+param(
+  [int]$ListenPort = 9223,
+  [string]$TargetHost = '127.0.0.1',
+  [int]$TargetPort = 9222
+)
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Net;
+using System.Net.Sockets;
+using System.Threading;
+
+public static class TcpRelay {
+    public static void Start(int listenPort, string targetHost, int targetPort) {
+        var listener = new TcpListener(IPAddress.Any, listenPort);
+        listener.Start();
+        while (true) {
+            var client = listener.AcceptTcpClient();
+            var t = new Thread(() => Handle(client, targetHost, targetPort));
+            t.IsBackground = true;
+            t.Start();
+        }
+    }
+
+    private static void Handle(TcpClient client, string targetHost, int targetPort) {
+        try {
+            using (client)
+            using (var target = new TcpClient(targetHost, targetPort)) {
+                using (var cs = client.GetStream())
+                using (var ts = target.GetStream()) {
+                    var t1 = new Thread(() => Pump(cs, ts));
+                    t1.IsBackground = true;
+                    t1.Start();
+                    Pump(ts, cs);
+                    t1.Join();
+                }
+            }
+        } catch {}
+    }
+
+    private static void Pump(System.IO.Stream src, System.IO.Stream dst) {
+        var buf = new byte[65536];
+        try {
+            int n;
+            while ((n = src.Read(buf, 0, buf.Length)) > 0) {
+                dst.Write(buf, 0, n);
+                dst.Flush();
+            }
+        } catch {}
+        try { dst.Close(); } catch {}
+    }
+}
+"@
+
+Write-Host "relay listening on 0.0.0.0:$ListenPort -> $TargetHost`:$TargetPort"
+[TcpRelay]::Start($ListenPort, $TargetHost, $TargetPort)

package/.tfcore/utils/tf-checklist-edit.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""tf-checklist-edit.py — the checklist edits the bug scripts share (Sitting 4c, 2026-09-06).
+
+Imported by tf-triage.py and tf-log-miss.py; not run on its own. Every function takes the
+checklist path, edits the file in place and returns what it did. The shapes follow
+docs/TechieFlow-Document-Schemas.md §3.4: the six-cell row, the `<a id="d-req-…">` entry, one
+acceptance line, a Remarks cell of at most 60 words.
+"""
+import datetime
+import os
+import re
+
+ROW = re.compile(r"^(\s*\|\s*`?)(REQ-[A-Z]+-\d+)(`?\s*\|)")
+TODAY = datetime.date.today().isoformat()
+
+
+def read(p):
+    with open(p, encoding="utf-8") as f:
+        return f.read()
+
+
+def write(p, s):
+    with open(p, "w", encoding="utf-8") as f:
+        f.write(s)
+
+
+def words(s, n=60):
+    w = s.split()
+    return s if len(w) <= n else " ".join(w[:n]) + "…"   # the ellipsis rides on the last word: the checker counts words, and a bare "…" was a 61st (miss 29)
+
+
+def rows(text):
+    """id -> {status, pct, remarks, title, line_no}"""
+    out = {}
+    for i, line in enumerate(text.splitlines()):
+        m = ROW.match(line)
+        if m:
+            c = [x.strip() for x in line.strip().strip("|").split("|")]
+            if len(c) >= 6:
+                pct = re.sub(r"[^0-9]", "", c[3])
+                out[m.group(2).upper()] = {"status": c[2].strip("`* "), "pct": int(pct) if pct.isdigit() else None,
+                                           "remarks": c[4], "title": c[1].strip("`* "), "line_no": i}
+    return out
+
+
+def set_cells(path, rid, status=None, pct=None, remark=None, append_remark=None):
+    """rewrite the Status, % and Remarks cells of one row; returns the prior cells or None"""
+    text = read(path)
+    lines = text.splitlines(keepends=True)
+    prior = None
+    for i, line in enumerate(lines):
+        m = ROW.match(line)
+        if not m or m.group(2).upper() != rid.upper():
+            continue
+        nl = "\r\n" if line.endswith("\r\n") else "\n"
+        c = line.rstrip("\r\n").strip().strip("|").split("|")
+        if len(c) < 6:
+            break
+        prior = {"status": c[2].strip().strip("`* "), "pct": c[3].strip(), "remarks": c[4].strip()}
+        if status is not None:
+            c[2] = f" {status} "
+        if pct is not None:
+            c[3] = f" {pct}% " if "%" in c[3] or c[3].strip() == "" else f" {pct} "
+        if remark is not None:
+            c[4] = f" {words(remark.replace('|', '/'))} "
+        elif append_remark:
+            c[4] = f" {words((prior['remarks'] + ' ' + append_remark.replace('|', '/')).strip())} "
+        lines[i] = "|" + "|".join(c) + "|" + nl
+        break
+    if prior is not None:
+        write(path, "".join(lines))
+    return prior
+
+
+def next_id(text, prefix):
+    ids = [int(m.group(1)) for m in re.finditer(rf"REQ-{prefix}-(\d{{3}})", text)]
+    return f"REQ-{prefix}-{(max(ids) + 1 if ids else 1):03d}"
+
+
+def add_row(path, prefix, title, acceptance, section=None, remark=None, status="Not Started", mockup=None, brd="BRD-pending"):
+    """append a row to the Requirements Status table and a detail entry under `section`
+    (a new section at the end when it does not exist); returns the new id"""
+    text = read(path)
+    rid = next_id(text, prefix)
+    nl = "\r\n" if "\r\n" in text else "\n"
+    lines = text.split(nl)
+    # the table: after the last REQ row
+    last = max((i for i, l in enumerate(lines) if ROW.match(l)), default=None)
+    if last is None:
+        raise SystemExit("no Requirements Status table with REQ rows in " + path)
+    remark = words((remark or f"logged from UAT {TODAY}").replace("|", "/"))
+    anchor = f"d-{rid.lower()}"
+    lines.insert(last + 1, f"| {rid} | {title.replace('|', '/')} | {status} | 0% | {remark} | [d](#{anchor}) |")
+    # the entry
+    entry = [f"- <a id=\"{anchor}\"></a> **{rid}** ({brd}) {title}" + (f" Mockup: {mockup}" if mockup else ""),
+             f"  - *Acceptance:* {acceptance}", ""]
+    sec_idx = None
+    if section:
+        for i, l in enumerate(lines):
+            if re.match(rf"^##\s+(?:page|screen)?\s*:?\s*{re.escape(section)}\s*$", l, re.I):
+                sec_idx = i
+                break
+    if sec_idx is not None:
+        # after the last entry of that section: the line before the next "## " heading
+        j = sec_idx + 1
+        while j < len(lines) and not lines[j].startswith("## "):
+            j += 1
+        while j > sec_idx + 1 and lines[j - 1].strip() == "":
+            j -= 1
+        lines[j:j] = [""] + entry[:-1]
+    else:
+        heading = f"## {section}" if section else "## Logged from UAT"
+        if not any(l.strip() == heading for l in lines):
+            lines += ["", heading, ""]
+        lines += entry[:-1]
+    write(path, nl.join(lines).rstrip(nl) + nl)
+    return rid
+
+
+def demote(path, rid, symptom, kind=None, evidence=None, source="owner", prefix="⚠ UAT bug"):
+    """Needs re-verify, % capped at 75, a dated Remark; returns the prior cells"""
+    r = rows(read(path)).get(rid.upper())
+    if not r:
+        return None
+    pct = min(r["pct"] if r["pct"] is not None else 75, 75)
+    ev = f"evidence: {evidence}" if evidence else f"evidence: {source} report"
+    remark = f"{prefix} {TODAY}: {symptom} ({ev}" + (f"; kind: {kind}" if kind else "") + ")"
+    return set_cells(path, rid, status="Needs re-verify", pct=pct, remark=remark)
+
+
+def note(path, rid, text):
+    """a dated remark, no status change"""
+    return set_cells(path, rid, append_remark=f"{TODAY} triage: {text}")