@techierathore/techieflow 1.0.4 → 1.1.0

package/.tfcore/utils/tf-mockup-parity.sh

@@ -5,6 +5,17 @@
 #        --screen login=/login --screen harness=/harness --screen export=/export \
 #        --cookie 'AuthCookie=<value from your Playwright login>' \
 #        --json-out tests/.artifacts/mockup-parity/run.json
+#   A sign-in the page keeps for itself sets no cookie (AppManager TF-011): give it
+#        --login-path /login --user <u> --password <p>   (or --storage-state <file>)
+#   and each screen is opened in a tab that signed in through the form, the way
+#   tf-verify-screens.sh does; `widths[].reached` in the JSON says how a 401 screen was reached.
+#   A desktop head (Lekhak TF-006): --cdp http://<host>:9223 in place of --base attaches to the
+#   running app, as tf-verify-screens.sh --cdp does, and opens each route by pushState.
+#   The app is compared in the mockup's theme: the mockup's data-*theme/mode/scheme attributes on
+#   <html> and <body>, and a light/dark mode class there (class="dark", Lekhak TF-013), are set on the
+#   app page for the comparison and put back after (Lekhak TF-010);
+#   --keep-app-theme compares the theme the app shows. A mockup box marked data-tf-state or
+#   data-state-testid (another state of the screen) is left out of the comparison (Lekhak TF-011).
 #
 # WHAT IT ASKS: "does the built screen carry the structure its approved mockup
 # draws?" — at the same viewports, comparing STRUCTURE, never pixels. Pixel diffing
@@ -47,7 +58,7 @@ set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-case "${1:-}" in -h|--help) sed -n '2,42p' "$0"; exit 0 ;; esac
+case "${1:-}" in -h|--help) sed -n '2,48p' "$0"; exit 0 ;; esac
 
 command -v node >/dev/null 2>&1 || {
   echo "tf-mockup-parity: node is required (verify-phase §1 installs the verify environment)." >&2
@@ -62,4 +73,5 @@ node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1
   exit 4
 }
 
-exec node "$HERE/tf-mockup-parity.mjs" "$@"
+source "$HERE/tf-lock.sh"; tf_take_lock mockup-parity   # one browser check at a time (TF-048)
+node "$HERE/tf-mockup-parity.mjs" "$@"

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

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""tf-owner-text.py — check text written for the owner (MISS-TechieFlow-20260911-03).
+
+    bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] <file> ...
+    bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] --stdin      # the closing message
+
+Four checks, one per mistake that reached the owner in TfLens's hand-off of 2026-09-11
+(MISS-TfLens-20260911-01 to -03, and a fourth: two problems fixed upstream reported as open):
+
+  words     a word from .tfcore/standards/owner-words.txt, or a script's internal name such as
+            duration_s or PHASES_TOP_KEYS, in a sentence the owner reads
+  upstream  an upstream problem (an entry id in docs/*-Feedback.md: TF-022, TR-010 …) that is
+            still open sits in a table saying what it affects and whether it blocks or breaks
+            anything, and appears in a code block, which is the prompt that gets it fixed; one the
+            feedback file records as fixed upstream or closed is described as fixed or closed
+  commands  a framework command named in a sentence (*verify) appears in a code block holding
+            the line to paste
+  final     with --final, the text is a command's closing message and carries a code block: the
+            next prompt
+
+Text inside ``` blocks is what the owner pastes, so the words check skips it. A document that has
+its own template (BRD, checklist, feedback file …) is skipped: tf-doc-check.sh owns its shape.
+Exit 0 clean, 1 a FAIL, 2 could not run. Python 3 standard library only.
+"""
+from __future__ import annotations
+
+import glob
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ANY_ID = re.compile(r"(?<![\w-])([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+)\b")
+SCRIPT_NAME = re.compile(r"(?<![\w/.\-])([A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+)(?![\w/\-]|\.\w)")
+COMMAND = re.compile(r"(?<![\w*])\*([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\b")
+# a sentence that puts a command in front of the owner as work still to do
+TO_RUN = re.compile(r"(?i)\b(run|rerun|re-run|pending|next|not (?:yet )?(?:been )?run|still|should|must|"
+                    r"needs?|to do|waiting|before|then)\b")
+COMMANDS = {"verify", "build-phase", "fix-issues", "triage-issues", "triage-and-fix", "amend-docs",
+            "refresh-status", "handoff-phase", "log-miss", "deploy-checklist", "day1-greenfield",
+            "day1-brownfield", "devguide", "productguide", "metrics", "split-brd", "mockups", "yolo"}
+TEMPLATED = re.compile(
+    r"(?i)(?:-P\d+)?-(BRD|Architecture|UIDesign|Checklist|Deployment-Checklist(?:-[\w]+)?|Coding-Standards|"
+    r"UsageGuide|Usage-Guide|DevGuide|ProductGuide|Phases|Brief|Decision-Request|[\w.]+-Feedback|Misses)\.md$"
+    r"|(?:^|/)PROJECT-STATUS\.md$")
+
+
+def load_words(root):
+    for base in (os.path.join(root, ".tfcore", "standards"), os.path.join(HERE, "..", "standards")):
+        p = os.path.join(base, "owner-words.txt")
+        if os.path.isfile(p):
+            out = {}
+            for line in open(p, encoding="utf-8"):
+                if line.strip() and not line.lstrip().startswith("#") and "|" in line:
+                    w, say = (x.strip() for x in line.split("|", 1))
+                    out[w.lower()] = say
+            return out
+    return {}
+
+
+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."""
+    sys.path.insert(0, HERE)
+    import tf_feedback
+    return tf_feedback.state_map(root)
+
+
+def split_text(text):
+    """-> (prose lines [(n, line)], the text inside code blocks)."""
+    prose, fenced, fence = [], [], None
+    for n, line in enumerate(text.splitlines(), 1):
+        m = re.match(r"^\s*(```|~~~)", line)
+        if m:
+            fence = None if fence == m.group(1) else (fence or m.group(1))
+            continue
+        (fenced if fence else prose).append((n, line) if not fence else line)
+    return prose, "\n".join(fenced)
+
+
+def units(prose):
+    """Group prose lines into the unit a sentence is read in: a table row (with its table's
+    header) or a paragraph. -> [(first line no, text, header or None)]"""
+    out, para, header, in_table = [], [], None, False
+
+    def flush():
+        if para:
+            out.append((para[0][0], "\n".join(t for _n, t in para), None))
+            para.clear()
+
+    for n, line in prose:
+        if line.lstrip().startswith("|"):
+            flush()
+            if not in_table:
+                header, in_table = line, True
+            elif not re.match(r"^\s*\|?\s*:?-{2,}", line):
+                out.append((n, line, header))
+            continue
+        in_table = False
+        if line.strip():
+            para.append((n, line))
+        else:
+            flush()
+    flush()
+    return out
+
+
+def next_command(root):
+    p = os.path.join(root, "PROJECT-STATUS.md")
+    if not os.path.isfile(p):
+        return ""
+    m = re.search(r"(?ms)^##\s+Next command to run.*?```[^\n]*\n(.*?)```", open(p, encoding="utf-8").read())
+    return m.group(1).strip().splitlines()[0] if m and m.group(1).strip() else ""
+
+
+def check(text, label, root, final=False, words=None, ups=None):
+    fails = []
+    fail = lambda n, msg: fails.append(f"FAIL {label}{':' + str(n) if n else ''}: {msg}")
+    words = load_words(root) if words is None else words
+    ups = upstream_state(root) if ups is None else ups
+    prose, fenced = split_text(text)
+
+    # 1. words
+    seen = set()
+    for n, line in prose:
+        plain = re.sub(r"`[^`]*`", " ", re.sub(r"https?://\S+|\]\([^)]*\)", " ", line))
+        plain = re.sub(r'"[^"\n]{1,30}"|“[^”\n]{1,30}”', " ", plain)   # a word quoted to name it is not used
+        for w, say in words.items():
+            if w not in seen and re.search(rf"(?i)(?<![\w-]){re.escape(w)}s?(?![\w-])", plain):
+                seen.add(w)
+                fail(n, f'"{w}" is a word the owner has to look up; say "{say}"')
+        for name in SCRIPT_NAME.findall(re.sub(r"https?://\S+|\]\([^)]*\)", " ", line)):
+            if name not in seen:
+                seen.add(name)
+                fail(n, f'"{name}" is a name inside a script; say in words what it is')
+
+    # 2. upstream problems. A fixed or closed one must read as such wherever it is named; an open
+    # one must be explained once, in a table row saying what it affects and whether it blocks or
+    # breaks anything, and must appear in the prompt that gets it fixed.
+    us = units(prose)
+    mentions = {}
+    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]
+        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]
+            wrong = next((n for n, txt, h in ms
+                          if not all(re.search(r"(?i)\b(fixed|closed)\b", s) for s in said(txt, h))), None)
+            if wrong is not None:
+                fail(wrong, f"{rid} is written about as an open problem, but {where} records it as "
+                            f"{'fixed upstream' if st == 'fixed' else 'closed'}; say so, and say what re-checks it here")
+            continue
+        explained = any(h is not None and "affect" in h.lower() and re.search(r"(?i)block|break", h)
+                        for _n, _t, h in ms)
+        if not explained:
+            fail(ms[0][0], f"{rid} is named without saying what it affects and whether it blocks or breaks "
+                           f"anything: put it in a table with the columns Problem | What it affects | Does it block or break anything")
+        elif not re.search(rf"(?<![\w-]){re.escape(rid)}\b", fenced):
+            fail(ms[0][0], f"{rid} is open and no code block gives the prompt that gets it fixed")
+
+    # 3. commands: one presented as something to run needs the line to paste. Naming a command
+    # to say what it did ("*build-phase means build every unfinished row") needs nothing.
+    known = COMMANDS | {os.path.splitext(os.path.basename(p))[0]
+                        for p in glob.glob(os.path.join(root, ".tfcore", "tasks", "*.md"))
+                        if not os.path.basename(p).startswith("_")}
+    named = {}
+    for n, txt, _h in us:
+        plain = re.sub(r"`[^`]*`", " ", txt)                 # `run-void` is a name, not a cue
+        plain = re.sub(r"(?i)\b(?:do not|don't|never|no need to|need not)\s+run\b", " ", plain)
+        if not TO_RUN.search(plain):
+            continue
+        for c in COMMAND.findall(txt):
+            if c in known:
+                named.setdefault(c, n)
+    for c, n in sorted(named.items(), key=lambda kv: kv[1]):
+        if not re.search(rf"\*{re.escape(c)}\b", fenced):
+            fail(n, f"*{c} is named, but no code block holds the line to paste for it "
+                    f"(tf-status-facts.sh prints it in both harness forms)")
+
+    # 4. a command's closing message ends by handing over the next prompt
+    if final and not fenced.strip():
+        nc = next_command(root)
+        fail(0, "the closing message gives no next prompt; end with a code block holding the line to paste"
+                + (f" — PROJECT-STATUS.md says: {nc}" if nc else ""))
+    return fails
+
+
+def main(argv):
+    root, final, stdin, files = os.getcwd(), False, False, []
+    it = iter(argv)
+    for a in it:
+        if a == "--root":
+            root = os.path.abspath(next(it, "."))
+        elif a == "--final":
+            final = True
+        elif a == "--stdin":
+            stdin = True
+        elif a in ("-h", "--help"):
+            print(__doc__)
+            return 0
+        else:
+            files.append(a)
+    if not stdin and not files:
+        print(__doc__)
+        return 2
+    words, ups, fails, checked = load_words(root), upstream_state(root), [], 0
+    if stdin:
+        fails += check(sys.stdin.read(), "the closing message", root, final, words, ups)
+        checked += 1
+    for f in files:
+        rel = os.path.relpath(os.path.abspath(f), root)
+        if TEMPLATED.search(rel.replace("\\", "/")):
+            print(f"SKIP {rel}: it has a template; tf-doc-check.sh checks it")
+            continue
+        if not os.path.isfile(f):
+            fails.append(f"FAIL {rel}: file not found")
+            continue
+        # a document handed over is held to the first three checks; ending on the next prompt is
+        # the closing message's job
+        fails += check(open(f, encoding="utf-8", errors="replace").read(), rel, root, False, words, ups)
+        checked += 1
+    for line in fails:
+        print(line)
+    print(f"tf-owner-text: {len(fails)} FAIL in {checked} text(s)")
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# tf-owner-text.sh — check text written for the owner: plain words, every upstream problem with
+# what it affects and the prompt that fixes it, every named command with the line to paste, and
+# a command's closing message ending on the next prompt (MISS-TechieFlow-20260911-03).
+#
+#   bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] <file> ...
+#   printf '%s' "<message>" | bash .tfcore/utils/tf-owner-text.sh --final --stdin
+#
+# The Stop hook runs it on a command's closing message and on every free-form document that
+# message hands the owner. Details: tf-owner-text.py. Exit 0 clean, 1 a FAIL, 2 could not run.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-owner-text: python3 is required" >&2; exit 2; }
+exec python3 "$HERE/tf-owner-text.py" "$@"

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

@@ -38,7 +38,18 @@ case "${1:-}" in
       NOW="$(sed -n 's/.*"started":"\([^"]*\)".*/\1/p' "$FILE")"
       echo "tf-phase: started taken from the supervisor's marker ($NOW)" >&2
     fi
-    printf '{"cmd":"%s","app":"%s","started":"%s"}\n' "$CMD" "$APP" "$NOW" > "$FILE"
+    # A command started inside another one (*fix-issues and *build-phase run *verify inline) keeps
+    # 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=""
+    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\"},"
+    fi
+    printf '{%s"cmd":"%s","app":"%s","started":"%s"}\n' "$OUTER" "$CMD" "$APP" "$NOW" > "$FILE"
     echo "$NOW"
     echo "tf-phase: $CMD${APP:+ $APP} started $NOW (marker .tfcore/.session/phase.json)" >&2
     # The document-check baseline (Sitting 4c, 2026-09-06): the findings the checklists and the
@@ -68,6 +79,9 @@ case "${1:-}" in
       else
         echo "tf-phase: framework self-check clean" >&2
       fi
+      # upstream fixes this project has not re-checked: passed through whole, because "clean"
+      # alone let an agent report two fixed problems to the owner as open (2026-09-11)
+      sed -n '/^Fixed upstream, not yet re-checked here/,/tf-feedback.sh <App> --close/p' <<<"$sc" | sed 's/^/tf-phase: /' >&2
     fi
     ;;
   goal)

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

@@ -0,0 +1,230 @@
+# tf-portable.sh — the few commands that differ between Linux/WSL (GNU tools, bash 4+) and a
+# stock Mac (bash 3.2 at /bin/bash, BSD sed/date/stat, no GNU coreutils). Sourced, not run:
+#   source "$(dirname "${BASH_SOURCE[0]}")/tf-portable.sh"
+# Every function uses the native tool when it is there, so Linux and WSL behave exactly as they
+# did before this file existed; the fallback runs only where the native tool is missing.
+# Plain functions only: sourcing it defines functions and nothing else (no variables, no traps,
+# no set options). Bash 3.2 safe. The check tests/portability/run.sh keeps GNU-only and
+# bash-4-only constructs out of every other script; add a function here instead.
+#
+#   tf_timeout DURATION CMD [ARG...]     timeout(1); 124 when the time runs out
+#   tf_setsid [--exec] CMD [ARG...]      setsid(1); --exec replaces the calling (sub)shell
+#   tf_sed_inplace SED-ARG... FILE       sed -i on GNU and BSD sed, no backup file left behind
+#   tf_stat_mtime FILE                   modification time, epoch seconds
+#   tf_stat_size FILE                    size in bytes
+#   tf_date_from [-u] WHEN [+FORMAT]     date -d WHEN; WHEN is @EPOCH, "-10 min", "+2 hours",
+#                                        "now", or YYYY-MM-DD[( |T)HH:MM[:SS]][Z]
+#   tf_epoch_frac                        seconds since the epoch with a fraction (date +%s.%N)
+#   tf_realpath PATH                     realpath(1) as GNU has it (the last part may be missing)
+#   tf_relpath BASE PATH                 realpath --relative-to=BASE PATH
+#   tf_read_lines ARRAY-NAME             mapfile -t ARRAY-NAME (reads stdin)
+
+# ---- tf_timeout ---------------------------------------------------------------------------
+# GNU timeout, then Homebrew's gtimeout, then a perl fallback (perl ships with macOS). The
+# fallback runs the command in its own process group, sends the group TERM when the time is up
+# and exits 124, the code timeout(1) uses; otherwise it exits with the command's own status
+# (128+N when signal N ended it), and 126/127 when the command cannot be run, as timeout(1) does.
+tf_timeout() {
+  if [ $# -lt 2 ]; then echo "tf_timeout: usage: tf_timeout DURATION COMMAND [ARG...]" >&2; return 125; fi
+  if command -v timeout >/dev/null 2>&1; then timeout "$@"; return $?; fi
+  if command -v gtimeout >/dev/null 2>&1; then gtimeout "$@"; return $?; fi
+  _tf_timeout_perl "$@"
+}
+_tf_timeout_perl() {
+  local dur="$1" secs; shift
+  case "$dur" in
+    *s) secs="${dur%s}" ;;
+    *m) secs="$(awk -v n="${dur%m}" 'BEGIN { print n * 60 }')" ;;
+    *h) secs="$(awk -v n="${dur%h}" 'BEGIN { print n * 3600 }')" ;;
+    *d) secs="$(awk -v n="${dur%d}" 'BEGIN { print n * 86400 }')" ;;
+    *) secs="$dur" ;;
+  esac
+  case "$secs" in ''|*[!0-9.]*) echo "tf_timeout: invalid time interval '$dur'" >&2; return 125 ;; esac
+  perl -e '
+    use strict; use POSIX ();
+    my $secs = shift @ARGV;
+    my $pid = fork();
+    if (!defined $pid) { print STDERR "tf_timeout: fork failed: $!\n"; exit 125; }
+    if ($pid == 0) {
+      setpgrp(0, 0);   # its own process group, so the whole tree is stopped, as timeout(1) does
+      exec { $ARGV[0] } @ARGV;
+      my $code = $!{ENOENT} ? 127 : 126;
+      print STDERR "tf_timeout: failed to run command \x27$ARGV[0]\x27: $!\n";
+      POSIX::_exit($code);
+    }
+    my $fired = 0;
+    $SIG{ALRM} = sub { $fired = 1; kill("TERM", -$pid) or kill("TERM", $pid); };
+    $SIG{TERM} = sub { kill "TERM", $pid; };
+    $SIG{INT}  = sub { kill "INT", $pid; };
+    if ($secs > 0) {
+      my $whole = int($secs); $whole++ if $whole < $secs;   # alarm takes whole seconds; round up
+      alarm($whole);
+    }
+    my $got;
+    do { $got = waitpid($pid, 0); } while ($got == -1 && $!{EINTR});
+    my $status = $?;
+    alarm(0);
+    exit 124 if $fired;
+    exit(128 + ($status & 127)) if $status & 127;
+    exit($status >> 8);
+  ' "$secs" "$@"
+}
+
+# ---- tf_setsid ----------------------------------------------------------------------------
+# util-linux setsid, then python3 os.setsid, then perl POSIX::setsid. As setsid(1) does, a
+# caller that already leads a process group is forked first and the parent returns 0 at once.
+# --exec: replace the calling (sub)shell with it, like `exec setsid CMD`.
+tf_setsid() {
+  local ex=""
+  if [ "${1:-}" = "--exec" ]; then ex=exec; shift; fi
+  if [ $# -lt 1 ]; then echo "tf_setsid: usage: tf_setsid [--exec] COMMAND [ARG...]" >&2; return 1; fi
+  if command -v setsid >/dev/null 2>&1; then $ex setsid "$@"
+  elif command -v python3 >/dev/null 2>&1; then $ex python3 -c "$(_tf_setsid_py)" "$@"
+  elif command -v perl >/dev/null 2>&1; then $ex perl -e "$(_tf_setsid_pl)" "$@"
+  else echo "tf_setsid: needs setsid, python3 or perl; none is on PATH" >&2; return 127
+  fi
+}
+_tf_setsid_py() {
+  printf '%s\n' \
+    'import os, sys' \
+    'if os.getpgrp() == os.getpid():' \
+    '    if os.fork() != 0:' \
+    '        os._exit(0)' \
+    'os.setsid()' \
+    'try:' \
+    '    os.execvp(sys.argv[1], sys.argv[1:])' \
+    'except OSError as e:' \
+    '    sys.stderr.write("setsid: failed to execute %s: %s\n" % (sys.argv[1], e.strerror))' \
+    '    os._exit(127 if e.errno == 2 else 126)'
+}
+_tf_setsid_pl() {
+  printf '%s\n' \
+    'use POSIX ();' \
+    'if (getpgrp() == $$) { my $p = fork(); POSIX::_exit(0) if $p; }' \
+    'POSIX::setsid();' \
+    'exec { $ARGV[0] } @ARGV;' \
+    'my $c = $!{ENOENT} ? 127 : 126;' \
+    'print STDERR "setsid: failed to execute $ARGV[0]: $!\n";' \
+    'POSIX::_exit($c);'
+}
+
+# ---- tf_sed_inplace -----------------------------------------------------------------------
+# GNU sed takes -i alone; BSD sed needs -i '' for "no backup". The sed script itself must be
+# one both seds understand (no \s, \+, \n in a replacement, 0,/re/ addresses).
+tf_sed_inplace() {
+  if [ $# -lt 2 ]; then echo "tf_sed_inplace: usage: tf_sed_inplace SED-ARG... FILE" >&2; return 2; fi
+  if sed --version >/dev/null 2>&1; then sed -i "$@"; else sed -i '' "$@"; fi
+}
+
+# ---- tf_stat_mtime / tf_stat_size ---------------------------------------------------------
+tf_stat_mtime() {
+  if stat -c %Y / >/dev/null 2>&1; then stat -c %Y "$1"; else stat -f %m "$1"; fi
+}
+tf_stat_size() {
+  if stat -c %s / >/dev/null 2>&1; then stat -c %s "$1"; else stat -f %z "$1"; fi
+}
+
+# ---- tf_date_from -------------------------------------------------------------------------
+# GNU date reads almost anything with -d; BSD date reads @EPOCH with -r and a fixed layout
+# with -j -f. The WHEN forms listed at the top cover every caller in this framework. On GNU
+# date the WHEN is handed to date -d unchanged, so the output is exactly what it was.
+tf_date_from() {
+  local utc="" when fmt epoch
+  if [ "${1:-}" = "-u" ]; then utc="-u"; shift; fi
+  when="${1:-}"; fmt="${2:-}"
+  if [ -z "$when" ]; then echo "tf_date_from: usage: tf_date_from [-u] WHEN [+FORMAT]" >&2; return 1; fi
+  if date -d @0 +%s >/dev/null 2>&1; then
+    if [ -n "$fmt" ]; then date $utc -d "$when" "$fmt"; else date $utc -d "$when"; fi
+    return $?
+  fi
+  epoch="$(_tf_date_epoch $utc "$when")" || return 1
+  if [ -n "$fmt" ]; then date $utc -r "$epoch" "$fmt"; else date $utc -r "$epoch"; fi
+}
+# WHEN → epoch seconds without GNU date -d. @EPOCH, now and relative offsets are plain
+# arithmetic; an absolute date goes through BSD date -j -f (GNU date on a machine that has it).
+_tf_date_epoch() {
+  local utc="" when now n unit mult value layout
+  if [ "${1:-}" = "-u" ]; then utc="-u"; shift; fi
+  when="$1"; now="$(date +%s)"
+  case "$when" in
+    now) echo "$now"; return 0 ;;
+    @*) echo "${when#@}"; return 0 ;;
+  esac
+  case "$when" in
+    [+-][0-9]*|[0-9]*[a-z]*)
+      n="$(printf '%s' "$when" | sed -E 's/^([+-]?[0-9]+).*/\1/')"
+      unit="$(printf '%s' "$when" | sed -E 's/^[+-]?[0-9]+[[:space:]]*//; s/[[:space:]]*ago$//')"
+      case "$unit" in
+        s|sec|secs|second|seconds) mult=1 ;;
+        min|mins|minute|minutes) mult=60 ;;
+        hour|hours) mult=3600 ;;
+        day|days) mult=86400 ;;
+        week|weeks) mult=604800 ;;
+        *) mult="" ;;
+      esac
+      if [ -n "$mult" ]; then
+        n="${n#+}"
+        case "$when" in *ago) n=$(( -n )) ;; esac
+        echo $(( now + n * mult )); return 0
+      fi ;;
+  esac
+  value="$when"; layout=""
+  case "$value" in *Z) value="${value%Z}"; utc="-u" ;; esac
+  value="$(printf '%s' "$value" | sed 's/T/ /')"
+  case "$value" in
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) value="$value 00:00:00" ;;
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]" "[0-9][0-9]:[0-9][0-9]) value="$value:00" ;;
+  esac
+  case "$value" in
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]" "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]) layout="%Y-%m-%d %H:%M:%S" ;;
+  esac
+  if [ -z "$layout" ]; then echo "date: invalid date '$when'" >&2; return 1; fi
+  if date -d @0 +%s >/dev/null 2>&1; then date $utc -d "$value" +%s; else date $utc -j -f "$layout" "$value" +%s; fi
+}
+
+# ---- tf_epoch_frac ------------------------------------------------------------------------
+# GNU date +%s.%N; BSD date prints a literal N, so the fallback asks perl or python3.
+tf_epoch_frac() {
+  local v
+  v="$(date +%s.%N 2>/dev/null)"
+  case "$v" in *N|'') ;; *) printf '%s\n' "$v"; return 0 ;; esac
+  if command -v perl >/dev/null 2>&1; then perl -MTime::HiRes=time -e 'printf("%.9f\n", time)'
+  else python3 -c 'import time; print("%.9f" % time.time())'
+  fi
+}
+
+# ---- tf_realpath / tf_relpath -------------------------------------------------------------
+tf_realpath() {
+  if [ $# -ne 1 ]; then echo "tf_realpath: usage: tf_realpath PATH" >&2; return 1; fi
+  # GNU realpath (it has -m) only: the macOS 13+ realpath refuses a path whose last part does not
+  # exist yet, which GNU realpath and the fallback below both accept.
+  if realpath -m / >/dev/null 2>&1; then realpath "$1"; return $?; fi
+  python3 -c 'import os, sys
+p = sys.argv[1]
+if not os.path.exists(os.path.dirname(os.path.abspath(p)) or "/"):
+    sys.stderr.write("realpath: %s: No such file or directory\n" % p); sys.exit(1)
+print(os.path.realpath(p))' "$1"
+}
+tf_relpath() {
+  if [ $# -ne 2 ]; then echo "tf_relpath: usage: tf_relpath BASE PATH" >&2; return 1; fi
+  if realpath --relative-to=/ / >/dev/null 2>&1; then realpath --relative-to="$1" "$2"; return $?; fi
+  python3 -c 'import os, sys
+print(os.path.relpath(os.path.realpath(sys.argv[2]), os.path.realpath(sys.argv[1])))' "$1" "$2"
+}
+
+# ---- tf_read_lines ------------------------------------------------------------------------
+# mapfile -t NAME < <(cmd)  becomes  tf_read_lines NAME < <(cmd)
+# One element per line, newline removed, a last line without a newline kept, nothing else
+# touched (leading blanks and backslashes stay). NAME is emptied first, as mapfile does.
+tf_read_lines() {
+  case "${1:-}" in
+    ''|[0-9]*|*[!A-Za-z0-9_]*) echo "tf_read_lines: usage: tf_read_lines ARRAY-NAME < input" >&2; return 2 ;;
+  esac
+  local _tf_rl_line _tf_rl_i=0
+  eval "$1=()"
+  while IFS= read -r _tf_rl_line || [ -n "$_tf_rl_line" ]; do
+    eval "$1[\$_tf_rl_i]=\$_tf_rl_line"
+    _tf_rl_i=$(( _tf_rl_i + 1 ))
+  done
+  return 0
+}

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

@@ -12,7 +12,7 @@ Usage:
 Writes a sibling <file>.html for each input. Exit codes:
     0  all rendered
     1  a render failed
-    2  refused (checklist, or missing spec)
+    2  refused (checklist, miss log, feedback file, or missing spec)
 
 Dependency-free by design: Python 3 standard library only. The reference machine
 has no pandoc / python-markdown / node markdown library installed.
@@ -111,6 +111,27 @@ RAW_TAG = re.compile(
     re.I)
 
 
+# Where the page being rendered will live, and every page this run will write (Lekhak TF-015). A
+# relative link to a sibling .md is written as .html when that .html is there already or is written in
+# the same run, so an index of a split guide opens the rendered pages, not raw markdown. A link to a
+# markdown file that has no rendered twin (an agent document, a checklist) stays .md.
+LINK_CTX = {"page_dir": None, "batch": set()}
+MD_LINK = re.compile(r"^([^#?]+?)\.md((?:[?#].*)?)$", re.I)
+
+
+def md_link_to_html(href):
+    if not LINK_CTX["page_dir"] or re.match(r"^[a-z][a-z0-9+.-]*:|^/|^#", href, re.I):
+        return href                                      # a web link, an absolute path, an anchor
+    m = MD_LINK.match(href)
+    if not m:
+        return href
+    from urllib.parse import unquote
+    target = os.path.normpath(os.path.join(LINK_CTX["page_dir"], unquote(m.group(1)) + ".html"))
+    if os.path.isfile(target) or target in LINK_CTX["batch"]:
+        return m.group(1) + ".html" + m.group(2)
+    return href
+
+
 def inline(text):
     """Markdown inline -> HTML. Code spans and deliberate raw inline HTML are
     protected before escaping, so `<a id="d-req-ui-001"></a>` survives verbatim
@@ -136,7 +157,7 @@ def inline(text):
                   lambda m: '<img src="%s" alt="%s" style="max-width:100%%">'
                             % (m.group(2), m.group(1)), text)
     text = re.sub(r"\[([^\]]+)\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)",
-                  lambda m: '<a href="%s">%s</a>' % (m.group(2), m.group(1)), text)
+                  lambda m: '<a href="%s">%s</a>' % (md_link_to_html(m.group(2)), m.group(1)), text)
     text = re.sub(r"<(https?://[^>\s]+)>", r'<a href="\1">\1</a>', text)
 
     text = re.sub(r"\*\*\*(.+?)\*\*\*", r"<strong><em>\1</em></strong>", text, flags=re.S)
@@ -495,6 +516,26 @@ def is_miss_list(base, raw):
     return "Rewritten by `tf-misses-md.sh`" in raw[:2000]
 
 
+FEEDBACK_ENTRY = re.compile(r"^#{2,3}\s+[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+\b", re.M)
+
+
+def is_feedback_file(base, raw):
+    """Is this an upstream feedback file, or an ordinary document about feedback?
+
+    `docs/{App}-{Upstream}-Feedback.md` is read by the upstream's agent and by the
+    maintainer who fixes it, in markdown. Nobody opens an HTML copy; the status gate's
+    "every human document this command wrote" kept producing one anyway, and an owner
+    asked more than once for it to be deleted (Chatur TF-001).
+
+    Identify the document, as the two rules above do: the name must match AND the
+    content must carry the template's `| Upstream |` header row or an entry heading
+    that opens with its id (TF-001, TR-RAG-002). A customer-feedback summary has neither."""
+    if not re.search(r"-Feedback\.md$", base, re.I):
+        return False
+    head = raw[:8000]
+    return bool(re.search(r"^\|\s*Upstream\s*\|", head, re.M) or FEEDBACK_ENTRY.search(raw))
+
+
 NEXT_CMD_H2 = re.compile(r"^##\s+Next command to run\s*$", re.I)
 
 
@@ -561,8 +602,13 @@ def render(md_path, css, head_js, body_js, out_dir=None):
         raise Refused("%s is the derived miss log — it is read in markdown by agents "
                       "and by the owner, and is NEVER rendered to HTML "
                       "(html-render-shell §0)." % base)
+    if is_feedback_file(base, raw_probe):
+        raise Refused("%s is an upstream feedback file — it is read in markdown by the "
+                      "upstream's agent, and is NEVER rendered to HTML "
+                      "(html-render-shell §0)." % base)
 
     raw = raw_probe
+    LINK_CTX["page_dir"] = os.path.abspath(out_dir or os.path.dirname(os.path.abspath(md_path)))
     lines = raw.split("\n")
     fm, lines = frontmatter(lines)
 
@@ -702,6 +748,18 @@ def main(argv):
 
     css, head_js, body_js = load_shell(spec)
 
+    # the pages this run will write, for md_link_to_html (a file the §0 ban refuses writes none)
+    LINK_CTX["batch"] = set()
+    for md in args:
+        try:
+            b = os.path.basename(md)
+            probe = open(md, encoding="utf-8").read().replace("\r\n", "\n")
+            if not (is_requirements_checklist(b, probe) or is_miss_list(b, probe) or is_feedback_file(b, probe)):
+                LINK_CTX["batch"].add(os.path.normpath(os.path.join(
+                    os.path.abspath(out_dir or os.path.dirname(os.path.abspath(md))), re.sub(r"\.md$", "", b) + ".html")))
+        except OSError:
+            pass
+
     rc = 0
     for md in args:
         if not os.path.isfile(md):