@techierathore/techieflow 1.0.4 → 1.1.1

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.
@@ -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
@@ -111,6 +125,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 +171,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)
@@ -184,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):
@@ -495,6 +532,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 +618,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 +764,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):

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-selfcheck.sh

@@ -117,7 +117,7 @@ else:
 # TF-019: a row can sit at `Needs re-verify` forever, which pinned the mode and dropped
 # every not-started row out of the list AND out of the counts, so a build pass could report
 # a phase finished with rows at 0%. The arithmetic is the check: every row lands in exactly
-# one of open / terminal / Blocked.
+# one of open / terminal / Blocked / roadmap.
 apps = app_names()
 if not apps:
     skip("tf-build-list", "no checklist in docs/ yet")
@@ -128,7 +128,7 @@ for app, phase, path in apps:
     if rc not in (0, 2):
         broken("tf-build-list", "%s: exited %d" % (label, rc), out.strip().splitlines()[0][:120] if out.strip() else "")
         continue
-    m = re.search(r"Mode: (\w+) — (\d+) row\(s\) to build; (\d+) terminal, (\d+) Blocked, (\d+) total", out)
+    m = re.search(r"Mode: (\w+) — (\d+) row\(s\) to build; (\d+) terminal, (\d+) Blocked, (?:(\d+) roadmap, )?(\d+) total", out)
     if not m:
         if "has no REQ rows" in out:
             skip("tf-build-list", "%s: checklist has no requirement rows yet" % label)
@@ -136,11 +136,11 @@ for app, phase, path in apps:
             broken("tf-build-list", "%s: no counts line to check" % label,
                    "the output shape changed; the arithmetic can no longer be verified")
         continue
-    mode, work, term, blocked, total = m.group(1), *(int(x) for x in m.groups()[1:])
-    if work + term + blocked != total:
+    mode, work, term, blocked, roadmap, total = m.group(1), *(int(x or 0) for x in m.groups()[1:])
+    if work + term + blocked + roadmap != total:
         broken("tf-build-list",
-               "%s: %d rows are in no category (%d open + %d terminal + %d blocked ≠ %d total)"
-               % (label, total - work - term - blocked, work, term, blocked, total),
+               "%s: %d rows are in no category (%d open + %d terminal + %d blocked + %d roadmap ≠ %d total)"
+               % (label, total - work - term - blocked - roadmap, work, term, blocked, roadmap, total),
                "a build pass trusting this list would leave those rows at 0%")
     else:
         ok("tf-build-list", "%s: %d rows, all accounted for (%s)" % (label, total, mode))
@@ -288,12 +288,45 @@ for name, cmd in (("tf-doc-check", ["bash", os.path.join(UTILS, "tf-doc-check.sh
         first = next((l for l in out.splitlines() if l.strip()), "")
         ok(name, "runs (exit %d)" % rc)
 
+# ---- 8. the upstream feedback files read as they are ------------------------------------
+# 2026-09-11: PROJECT-STATUS counted every ### heading as an entry and nothing as fixed, so
+# TfLens read "62 open of 62" and its agent told the owner two problems fixed two days earlier
+# were open (MISS-TechieFlow-20260911-04). The one reader is run here, on the real files, and
+# whatever an upstream team has fixed and this project has not re-checked is named below.
+waiting = []
+sys.path.insert(0, UTILS)
+try:
+    import tf_feedback
+    fb = tf_feedback.files(REPO)
+    if not fb:
+        skip("tf_feedback", "no upstream feedback files in this project")
+    else:
+        n = 0
+        for f in fb:
+            for e in tf_feedback.entries(f):
+                n += 1
+                if e["state"] == "fixed":
+                    waiting.append((e["id"], e["since"], os.path.basename(f)))
+        ok("tf_feedback", "%d feedback file(s), %d entries read; %d fixed upstream, not yet re-checked"
+           % (len(fb), n, len(waiting)))
+except Exception as e:
+    broken("tf_feedback", "crashed on this project's feedback files", str(e)[:120])
+
 # ---- output -----------------------------------------------------------------------------
 proj = os.path.basename(REPO.rstrip(os.sep))
 print("# tf-selfcheck — %s — the framework's own scripts against this project's real files" % proj)
 for l in lines:
     print(l)
 print()
+if waiting:
+    # Not a defect and not a failure: work this project owes. An upstream fix counts only once it
+    # has been re-checked here; until then it must never be reported to the owner as open.
+    print("Fixed upstream, not yet re-checked here — never report these as open problems:")
+    for rid, since, f in waiting:
+        print("  %-12s fixed %-10s %s" % (rid, since or "", f))
+    print("Re-check each with its entry's \"Verify from here\" step, then close it:")
+    print('  bash .tfcore/utils/tf-feedback.sh <App> --close <ID> "<what you ran and what it showed>"')
+    print()
 if not findings:
     print("Every framework script works on this project. Nothing to file.")
     raise SystemExit(0)

package/.tfcore/utils/tf-split-brd.py

@@ -223,7 +223,17 @@ def run(app, phase, force, add_missing, in_order=False):
     existing = read(cl_p) if os.path.isfile(cl_p) else ""
     if existing and not force and not add_missing:
         die(f"{cl_p} already exists; use --add-missing to append rows for new BRD items, or --force to rewrite", 1)
-    mapped = set(re.findall(r"\*BRD:\*\s*(BRD-\d+)", existing)) | set(re.findall(r"\((BRD-\d+)\)", existing))
+    # A BRD item already has a row when any row names it: on its `*BRD:*` detail line, or anywhere on
+    # its status-table line. The table form used to be read only as a bracket holding exactly one id,
+    # so "(BRD-76, Phase 3)" and "(BRD-118, BRD-120, Phase 3)" were invisible and --add-missing
+    # appended 44 rows to TfLens phase 3 for 13 new items, 31 of them copies of Verified rows (TF-025).
+    mapped = {b for line in re.findall(r"(?m)^.*\*BRD:\*.*$", existing) for b in re.findall(r"BRD-\d+", line)}
+    mapped |= {b for row in re.findall(r"(?m)^\|\s*REQ-.*$", existing) for b in re.findall(r"BRD-\d+", row)}
+    # ...and on the requirement's own line in its detail entry, with the lines indented under it. A
+    # checklist migrated from an older plan names its items there, as "(BRD-1, BRD-2)" or
+    # "*(BRD-84, BRD-85)*", with no *BRD:* line: AppManager's run appended a row for all 88 items (TF-001).
+    for block in re.findall(r"(?m)^\s*[-*]\s*(?:<a id=[^>]*>\s*</a>\s*)?\*\*REQ-[A-Z]+-\d{3}\*\*.*(?:\n[ \t]+\S.*)*", existing):
+        mapped |= set(re.findall(r"BRD-\d+", block))
     counters = other_phase_counters(app, cl_p, below=phase if in_order else None)
     if add_missing:
         for m in re.finditer(r"REQ-(UI|FN|RAG|NFR)-(\d{3})", existing):

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-evidence.sh

@@ -12,6 +12,7 @@
 #   4. the build verdict from tf-build.sh (skipped with --no-build)
 # Then the agent decides the interruption signature and runs tf-status-facts.sh for the gate.
 set -uo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/tf-portable.sh"   # GNU-only commands, for a stock Mac
 APP="${1:-}"; [[ -z "$APP" ]] && { sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
 shift
 BUILD=1; PHASE=""
@@ -22,7 +23,7 @@ while [[ $# -gt 0 ]]; do
     *) shift ;;
   esac
 done
-[[ -z "$PHASE" ]] && PHASE="$(grep -oE '^appPhase:\s*[0-9]+' .tfcore/core-config.yaml 2>/dev/null | grep -oE '[0-9]+' || echo 1)"
+[[ -z "$PHASE" ]] && PHASE="$(grep -oE '^appPhase:[[:space:]]*[0-9]+' .tfcore/core-config.yaml 2>/dev/null | grep -oE '[0-9]+' || echo 1)"
 [[ "$PHASE" -le 1 ]] && CL="docs/${APP}-Checklist.md" || CL="docs/${APP}-P${PHASE}-Checklist.md"
 ST="PROJECT-STATUS.md"
 
@@ -31,19 +32,20 @@ echo
 echo "## 1. What the stale status file claims (a hypothesis, not a fact)"
 if [[ -f "$ST" ]]; then
   grep -E '^(last_updated|current_phase|last_verified_build|last_verified_date):' "$ST" | sed 's/^/- /'
-  awk '/^## Next command to run/{p=1;next} /^## /{p=0} p' "$ST" | grep -E '^\s*/' | sed 's/^\s*/- next: /' | head -2
-  echo "- written: $(date -u -r "$ST" +%Y-%m-%dT%H:%M:%SZ)"
+  awk '/^## Next command to run/{p=1;next} /^## /{p=0} p' "$ST" | grep -E '^[[:space:]]*/' | sed 's/^[[:space:]]*/- next: /' | head -2
+  echo "- written: $(tf_date_from -u "@$(tf_stat_mtime "$ST")" +%Y-%m-%dT%H:%M:%SZ)"
 else
   echo "- no PROJECT-STATUS.md; treat as never written"
 fi
 echo
 echo "## 2. Files changed after the status file was written (src/ and tests/, newest first)"
 if [[ -f "$ST" ]]; then
-  mapfile -t NEWER < <(find src tests -type f -newer "$ST" \
-      -not -path '*/bin/*' -not -path '*/obj/*' -not -path '*/node_modules/*' -not -path '*/.artifacts/*' 2>/dev/null \
-      | xargs -r ls -t 2>/dev/null)
+  # xargs runs ls only when find listed something (GNU xargs -r; BSD xargs has no -r)
+  NEWER=(); _found="$(find src tests -type f -newer "$ST" \
+      -not -path '*/bin/*' -not -path '*/obj/*' -not -path '*/node_modules/*' -not -path '*/.artifacts/*' 2>/dev/null)"
+  [[ -n "$_found" ]] && tf_read_lines NEWER < <(printf '%s\n' "$_found" | xargs ls -t 2>/dev/null)
   echo "- ${#NEWER[@]} file(s)"
-  printf -- '- %s\n' "${NEWER[@]:0:30}"
+  printf -- '- %s\n' ${NEWER[@]+"${NEWER[@]:0:30}"}
   [[ ${#NEWER[@]} -gt 30 ]] && echo "- (${#NEWER[@]} in total; the rest with: find src tests -type f -newer PROJECT-STATUS.md)"
 else
   echo "- no status file to compare against"
@@ -51,9 +53,9 @@ fi
 echo
 echo "## 3. Checklist rows that look interrupted ($CL)"
 if [[ -f "$CL" ]]; then
-  grep -E '^\s*\|\s*`?REQ-' "$CL" | awk -F'|' '{id=$2; st=$4; gsub(/^[ `*]+|[ `*]+$/,"",id); gsub(/^[ ]+|[ ]+$/,"",st); print id" — "st}' \
+  grep -E '^[[:space:]]*\|[[:space:]]*`?REQ-' "$CL" | awk -F'|' '{id=$2; st=$4; gsub(/^[ `*]+|[ `*]+$/,"",id); gsub(/^[ ]+|[ ]+$/,"",st); print id" — "st}' \
     | grep -iE ' — (Implemented|In Progress|Needs re-verify|PARTIAL|FAIL)' | sed 's/^/- /' | head -40
-  n=$(grep -E '^\s*\|\s*`?REQ-' "$CL" | awk -F'|' '{print $4}' | grep -ciE 'Implemented|In Progress|Needs re-verify|PARTIAL|FAIL' || true)
+  n=$(grep -E '^[[:space:]]*\|[[:space:]]*`?REQ-' "$CL" | awk -F'|' '{print $4}' | grep -ciE 'Implemented|In Progress|Needs re-verify|PARTIAL|FAIL' || true)
   [[ "$n" == "0" ]] && echo "- none: every row is terminal, Blocked or not started"
 else
   echo "- $CL does not exist"