@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/utils/tf-routing-bind.sh

@@ -41,6 +41,63 @@ root = sys.argv[1]
 ryaml = os.path.join(root, ".tfcore", "routing.yaml")
 manifest_path = os.path.join(root, ".tfcore", ".session", "routing-bind.manifest")
 
+# --- migration: a project's routing.yaml is never overwritten -------------
+# `update-framework.sh` leaves a project's own routing.yaml alone on purpose, so a block added to
+# the framework default after the project was scaffolded would never reach it. Both delivery
+# routes run THIS script, so the migration lives here: a missing block is APPENDED, with the
+# Claude aliases filled in (opus/sonnet/haiku exist on every account) and the OpenCode lines left
+# empty, because guessing a model id for a provider this machine may not have would produce a
+# fallback that fails at the moment it is needed. Existing lines are never touched, and a file
+# that already has the block is left exactly as it is.
+MIGRATIONS = [
+    ("fallbacks:", """
+# Which models this tier drops to while its own is limited, in order, comma-separated.
+# Added by tf-routing-bind.sh. The opencode lines are OpenCode Go models
+# (https://opencode.ai/docs/go); change them if this project uses a different provider —
+# `opencode models` prints what this machine can reach.
+# The "limited until <time>" record is kept in this project, at
+# .tfcore/.session/model-cooldown.json. Uncomment to move it (relative to the project root, or
+# absolute); several projects sharing one file learn about a limit from each other.
+# cooldown_file: .tfcore/.session/model-cooldown.json
+# Full explanation: docs/TechieFlow-Routing-Guide.md §9.
+fallbacks:
+  frontier:
+    claude: opus, haiku
+    opencode: opencode-go/glm-5.3, opencode-go/kimi-k3, openai/gpt-5.6-sol
+  standard:
+    claude: haiku
+    opencode: opencode-go/mimo-v2.5, opencode-go/qwen3.8-max, openai/gpt-5.6-luna
+  economy:
+    claude: sonnet
+    opencode: opencode-go/deepseek-v4-flash, opencode-go/glm-5.3-flash, openai/gpt-5.6-luna
+"""),
+    ("billing:", """
+# How each harness is paid for, so a cost figure knows what it means (SCHEMA.md §2.5b).
+# subscription = a flat fee, marginal dollars are zero; metered = an API key, real money;
+# local = no bill; auto = work it out per model from OpenCode's own sign-in file.
+# Add a provider by name here to override the guess, e.g. "  myserver: local".
+billing:
+  claude: subscription
+  opencode: auto
+"""),
+]
+try:
+    _txt = open(ryaml, encoding="utf-8").read()
+    _added = []
+    for key, block in MIGRATIONS:
+        if not re.search(r"^%s\s*$" % re.escape(key), _txt, re.M):
+            if not _txt.endswith("\n"):
+                _txt += "\n"
+            _txt += block
+            _added.append(key.rstrip(":"))
+    if _added:
+        with open(ryaml, "w", encoding="utf-8", newline="\n") as _fh:
+            _fh.write(_txt)
+        print("tf-routing-bind: added %s to .tfcore/routing.yaml (nothing existing was changed)"
+              % " and ".join(_added))
+except FileNotFoundError:
+    pass
+
 # --- parse routing.yaml (flat format — see its header) --------------------
 cfg = {"enabled": False, "phases": {}, "subagents": {}, "tiers": {}, "effort": {}}
 sect = tier = None
@@ -67,8 +124,37 @@ try:
 except FileNotFoundError:
     pass  # no routing.yaml -> treat as disabled
 
+# A tier resolves to its own model UNLESS that model is on cooldown — a usage limit recorded by
+# tf-goal.sh in the per-machine file tf-model-pick.sh owns. Binding the fallback here is what stops
+# the sub-agents failing behind a main agent that already moved (Routing-Guide §8, 2026-09-06).
+_PICK = os.path.join(root, ".tfcore", "utils", "tf-model-pick.sh")
+_picked = {}
+
+
 def model_for(t, harness):
-    return cfg["tiers"].get(t, {}).get(harness)
+    declared = cfg["tiers"].get(t, {}).get(harness)
+    if not declared or t == "inherit":
+        return declared
+    if (t, harness) not in _picked:
+        got = declared
+        if os.path.isfile(_PICK):
+            try:
+                import subprocess
+                out = subprocess.run(["bash", _PICK, "pick", t, harness],
+                                     capture_output=True, text=True, timeout=20)
+                cand = (out.stdout or "").strip().splitlines()
+                cand = cand[-1].strip() if cand else ""
+                if cand and cand != "inherit":
+                    got = cand
+                elif cand == "inherit":
+                    got = None   # every model in the chain is limited: bind nothing, let it wait
+            except Exception:
+                pass
+        if got != declared:
+            print("tf-routing-bind: tier %s (%s) is on %s — %s is on cooldown"
+                  % (t, harness, got or "no model: the whole chain is limited", declared))
+        _picked[(t, harness)] = got
+    return _picked[(t, harness)]
 
 # --- remove previously generated artifacts (manifest-driven) --------------
 removed = 0

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

@@ -210,6 +210,13 @@ sub = ["%s=%s" % (k, v) for k, v in sorted(cfg["subagents"].items())]
 if sub:
     print("Subagents:  " + ", ".join(sub))
 print()
+print("When a model is limited (docs/TechieFlow-Routing-Guide.md §9):")
+print("  what each tier would run right now, and what is parked:")
+print("      bash .tfcore/utils/tf-model-pick.sh status")
+print("  the order a tier falls back in:  ... chain <tier> <claude|opencode>")
+print("  unpark by hand:                  ... clear <harness> [model]")
+print("  The supervisor parks a model by itself on a usage limit; tf-goal.sh --no-fallback stops it.")
+print()
 print("Escalation (ADVISORY — you apply it when you launch; nothing switches a model mid-run):")
 if cfg["escalation"]:
     for ph in sorted(cfg["escalation"]):

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

@@ -0,0 +1,356 @@
+#!/usr/bin/env bash
+# TechieFlow — the framework's own scripts, run against THIS project's real files.
+#
+#   bash .tfcore/utils/tf-selfcheck.sh [<repo>] [--report]
+#
+# WHY IT EXISTS. Nine framework defects reached TfLens in three weeks. Every one was
+# found mid-build, in the application's repository, and could only be fixed in the
+# framework's — so each cost a switch between repos, a feedback entry, a maintenance
+# sitting and a re-deploy. The defects were not exotic: a checklist with a row that
+# could never clear, a BRD carrying the anchors its own link checker demands, a metrics
+# file holding the framework's own verdicts. They were simply never run against a real
+# project's real files before the project ran them (MISS-TechieFlow-20260909-01).
+#
+# So this runs them here, first, and says which are broken ON THIS PROJECT. A FAIL is a
+# FRAMEWORK defect, never the project's: nothing here grades the application.
+#
+# Run it before a build pass, or any time. It writes nothing, boots nothing, and never
+# runs git. Python 3 standard library only.
+#
+# --report prints a ready-to-paste entry for the project's framework-feedback file, so
+# filing costs one paste instead of a page.
+#
+# EXIT: 0 every framework script works here · 1 at least one is broken · 3 cannot run.
+
+set -uo pipefail
+REPO="."; REPORT=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --report)  REPORT=1; shift ;;
+    -h|--help) sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)         REPO="$1"; shift ;;
+  esac
+done
+[[ -d "$REPO" ]] || { echo "tf-selfcheck: not a directory: $REPO" >&2; exit 3; }
+command -v python3 >/dev/null 2>&1 || { echo "tf-selfcheck: python3 required" >&2; exit 3; }
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+TF_REPO="$REPO" TF_UTILS="$HERE" TF_REPORT="$REPORT" python3 - <<'PY'
+import json, os, re, subprocess, sys
+
+REPO = os.path.abspath(os.environ["TF_REPO"])
+UTILS = os.environ["TF_UTILS"]
+TELEM = os.path.join(os.path.dirname(UTILS), "telemetry")
+REPORT = os.environ["TF_REPORT"] == "1"
+findings = []          # (script, what is wrong, the one-line fix hint)
+lines = []
+
+
+def ok(script, msg):
+    lines.append("ok    %-20s %s" % (script, msg))
+
+
+def broken(script, msg, hint=""):
+    lines.append("FAIL  %-20s %s" % (script, msg))
+    findings.append((script, msg, hint))
+
+
+def skip(script, msg):
+    lines.append("--    %-20s %s" % (script, msg))
+
+
+def run(cmd, cwd=REPO, timeout=120):
+    try:
+        p = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout or "") + (p.stderr or "")
+    except Exception as e:
+        return 99, str(e)
+
+
+def app_names():
+    """Every application this repo holds a checklist for. The checklist is the framework's
+    single source of truth, so its name is the app's name — no config value is trusted,
+    because core-config.yaml is rsynced between projects and is the thing most likely to
+    be stale (the same reason tf-gitignore-audit detects the stack from the tree)."""
+    d = os.path.join(REPO, "docs")
+    out = []
+    if os.path.isdir(d):
+        for f in sorted(os.listdir(d)):
+            m = re.match(r"^(.+?)(?:-P(\d+))?-Checklist\.md$", f)
+            if m and "Deployment" not in f:
+                out.append((m.group(1), int(m.group(2) or 1), os.path.join(d, f)))
+    return out
+
+
+# ---- 1. the deployed copy is intact ----------------------------------------------------
+# A framework script that will not even parse is the cheapest possible thing to catch and
+# the most expensive to meet mid-build.
+# Parsed in-process and the shells checked in ONE bash, not one subprocess per file:
+# 54 scripts meant 54 process launches and ten seconds, which is enough to make a check
+# that should run at the top of every command feel like a tax and get skipped.
+bad_parse, shells = [], []
+for folder in (UTILS, TELEM):
+    if not os.path.isdir(folder):
+        continue
+    for f in sorted(os.listdir(folder)):
+        full = os.path.join(folder, f)
+        if f.endswith(".py"):
+            try:
+                import ast
+                ast.parse(open(full, encoding="utf-8", errors="replace").read(), filename=full)
+            except SyntaxError:
+                bad_parse.append(f)
+        elif f.endswith(".sh"):
+            shells.append(full)
+if shells:
+    script = "for f in " + " ".join('"%s"' % x for x in shells) + \
+             '; do bash -n "$f" 2>/dev/null || echo "$f"; done'
+    rc, out = run(["bash", "-c", script])
+    bad_parse += [os.path.basename(x) for x in out.split() if x.strip()]
+if bad_parse:
+    broken("deployed copy", "%d script(s) do not parse: %s" % (len(bad_parse), ", ".join(bad_parse[:6])),
+           "re-run update-framework.sh; if it persists the framework shipped a broken script")
+else:
+    ok("deployed copy", "every framework script parses")
+
+# ---- 2. the working list accounts for every checklist row ------------------------------
+# 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 / roadmap.
+apps = app_names()
+if not apps:
+    skip("tf-build-list", "no checklist in docs/ yet")
+for app, phase, path in apps:
+    rc, out = run(["bash", os.path.join(UTILS, "tf-build-list.sh"), app] +
+                  ([] if phase <= 1 else ["--phase", str(phase)]))
+    label = "%s p%d" % (app, phase)
+    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+) 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)
+        else:
+            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, 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 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))
+
+# ---- 3. the BRD this project actually wrote can be read --------------------------------
+# TF-017: the ledger regex required **BRD-N** immediately after the bullet, and a real BRD
+# carries an <a id> anchor there because §9 cross-links need one. It matched 0 of 179 items.
+sys.path.insert(0, UTILS)
+for app, phase, _cl in apps:
+    brd = os.path.join(REPO, "docs", "%s-BRD.md" % app if phase <= 1 else "%s-P%d-BRD.md" % (app, phase))
+    if not os.path.isfile(brd):
+        continue
+    text = open(brd, encoding="utf-8", errors="replace").read()
+    # A struck-through item (~~**BRD-3**~~ *(removed …)*) is deliberately not a live
+    # requirement, and the ledger is right to skip it. Counting it as unread would make
+    # this check cry wolf on every mature BRD -- and a check that cries wolf is the one
+    # that gets skimmed (TF-012 failed 8 of 10 screens identically and trained exactly that).
+    # UNIQUE ids, not occurrences: an id named again in a cross-reference is the same
+    # requirement, and counting mentions made every BRD look short by however many times
+    # it referred to itself.
+    written_ids = {m.group(1) for m in re.finditer(r"\*\*(BRD-\d+)\*\*", text)
+                   if not re.search(r"~~\s*$", text[max(0, m.start() - 3):m.start()])}
+    written = len(written_ids)
+    try:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("_sb", os.path.join(UTILS, "tf-split-brd.py"))
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        read = len({(i["id"] if isinstance(i, dict) else i[0]) for i in mod.ledger(text)})
+    except Exception as e:
+        broken("tf-split-brd", "%s: could not read the BRD at all (%s)" % (app, type(e).__name__),
+               "*amend-docs --add-missing cannot append checklist rows")
+        continue
+    if written and read < written:
+        broken("tf-split-brd", "%s: reads %d of %d BRD items" % (app, read, written),
+               "new requirements must be added to the checklist by hand until this is fixed")
+    elif written:
+        ok("tf-split-brd", "%s: reads all %d BRD items" % (app, written))
+
+# ---- 4. the streams this project's figures are built on --------------------------------
+# TF-015: a run whose `ended` precedes its `started` was stored with a negative or invented
+# duration, and the two readers of the stream then disagreed about the same record.
+runs_p = os.path.join(REPO, "docs", "metrics", "runs.jsonl")
+if not os.path.isfile(runs_p):
+    skip("runs.jsonl", "no telemetry in this project yet")
+else:
+    neg = impossible = total_r = badline = 0
+    for l in open(runs_p, encoding="utf-8", errors="replace"):
+        l = l.strip()
+        if not l:
+            continue
+        try:
+            r = json.loads(l)
+        except Exception:
+            badline += 1
+            continue
+        total_r += 1
+        d = r.get("duration_s")
+        if isinstance(d, (int, float)) and d < 0:
+            neg += 1
+        s, e = r.get("started"), r.get("ended")
+        if isinstance(s, str) and isinstance(e, str) and e < s:
+            impossible += 1
+    if badline:
+        broken("runs.jsonl", "%d line(s) are not valid JSON" % badline, "those records are invisible to every figure")
+    if impossible or neg:
+        # NOT a failure. The emitter refuses these now and the reader discards them and
+        # prints how many -- so nothing is wrong with the framework here, and nothing can
+        # be done about the records either: the stream is append-only and the true start
+        # times are gone. Reported once as history, because calling it broken on every
+        # command for the life of the project is how a check earns being skimmed.
+        skip("runs.jsonl", "%d old record(s) end before they start — discarded from every "
+                           "duration figure, and the report says so" % impossible)
+    elif total_r:
+        ok("runs.jsonl", "%d run record(s), none impossible" % total_r)
+
+# ---- 5. the framework's own verdicts are not counted as this project's -----------------
+# TF-020: an FR verdict grades a framework requirement, not a screen, and pooling it into
+# an application segment raises that segment's first-pass rate with nothing on the output
+# to show it happened. SCHEMA §3 states the rule; the rollup has to apply it.
+gates_p = os.path.join(REPO, "docs", "metrics", "gates.jsonl")
+if not os.path.isfile(gates_p):
+    skip("tf-metrics", "no gate records in this project yet")
+else:
+    has_fr = False
+    for l in open(gates_p, encoding="utf-8", errors="replace"):
+        if '"req_class"' in l and '"FR"' in l:
+            has_fr = True
+            break
+    rc, out = run(["bash", os.path.join(TELEM, "tf-metrics.sh"), "--rollup", REPO, "--json"])
+    try:
+        data = json.loads(out)
+    except Exception:
+        broken("tf-metrics", "--rollup did not return readable JSON (exit %d)" % rc,
+               "no figure this project publishes can be checked against the reference")
+        data = None
+    if data is not None:
+        segs = data.get("live") or {}
+        if has_fr and "framework-requirement" not in segs:
+            broken("tf-metrics", "framework verdicts are pooled into %s" % ", ".join(sorted(segs) or ["nothing"]),
+                   "this project's first-pass rate is overstated")
+        else:
+            ok("tf-metrics", "rollup reads; %d segment(s), framework verdicts separate" % len(segs))
+
+# ---- 6. amendments to the miss log still fold -------------------------------------------
+# TF-006 and TF-018: a field added after a record was written can only be completed by an
+# amendment, and an amendment the reader will not fold is a fact silently lost.
+miss_p = os.path.join(REPO, "docs", "metrics", "misses.jsonl")
+if not os.path.isfile(miss_p):
+    skip("misses.jsonl", "no miss records in this project yet")
+else:
+    ids, amends, orphan = set(), 0, 0
+    for l in open(miss_p, encoding="utf-8", errors="replace"):
+        l = l.strip()
+        if not l:
+            continue
+        try:
+            r = json.loads(l)
+        except Exception:
+            continue
+        if r.get("kind") == "miss":
+            ids.add(r.get("miss_id"))
+        elif r.get("kind") == "miss-amend":
+            amends += 1
+            if r.get("miss_id") not in ids:
+                orphan += 1
+    if orphan:
+        broken("misses.jsonl", "%d amendment(s) name a miss that is not on this stream" % orphan,
+               "the information in them is not reaching any figure")
+    else:
+        ok("misses.jsonl", "%d miss(es), %d amendment(s), none orphaned" % (len(ids), amends))
+
+# ---- 7. the checks that read this project's documents run at all -----------------------
+for name, cmd in (("tf-doc-check", ["bash", os.path.join(UTILS, "tf-doc-check.sh")] +
+                   (["--app", apps[0][0]] if apps else []) + ["--warn"]),
+                  ("tf-gitignore-audit", ["bash", os.path.join(UTILS, "tf-gitignore-audit.sh"), REPO, "--dry-run"])):
+    if name == "tf-doc-check" and not apps:
+        skip(name, "no application documents yet")
+        continue
+    rc, out = run(cmd)
+    if rc in (99,) or "Traceback" in out:
+        broken(name, "crashed on this project's files",
+               (out.strip().splitlines() or [""])[-1][:120])
+    else:
+        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)
+
+print("%d framework defect(s) found. These are the FRAMEWORK's, not this project's —" % len(findings))
+print("nothing here graded the application. Do not work around them silently: file them,")
+print("and carry on (a framework defect blocks a row only when it stops the work).")
+if REPORT:
+    print()
+    print("--- paste into docs/%s-TechieFlow-Feedback.md ---" % proj)
+    for i, (script, msg, hint) in enumerate(findings, 1):
+        print()
+        print("## TF-xxx — %s: %s" % (script, msg))
+        print()
+        print("- **Severity:** major")
+        print("- **Blocks:** no")
+        print("- **Repro:** `bash .tfcore/utils/tf-selfcheck.sh` in this repository")
+        print("- **Expected:** the script works on this project's files")
+        print("- **Actual:** %s" % msg)
+        print("- **Encountered in:** tf-selfcheck, %s" % proj)
+        if hint:
+            print("- **Consequence:** %s" % hint)
+        print("- **Not fixable here** — `.tfcore/` is framework-owned and is replaced on the next update.")
+else:
+    print("Run again with --report for entries you can paste into the feedback file.")
+raise SystemExit(1)
+PY

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

@@ -85,7 +85,12 @@ def ledger(text):
     lines = text.splitlines()
     i = 0
     while i < len(lines):
-        m = re.match(r"^\s*[-*]\s*\*\*(BRD-\d+)\*\*\s*[—:-]+\s*(.*)$", lines[i])
+        # The anchor is not decoration: a BRD's §9 screen inventory links to each item as
+        # [BRD-21](#brd-21), markdown generates no id for bold text inside a list item, and
+        # tf-doc-check refuses a broken link -- so a real BRD carries `<a id="brd-N"></a>`
+        # here and this regex matched NONE of TfLens's 179 items. tests/regression tf_017.
+        m = re.match(r"^\s*[-*]\s*(?:<a id=[\"\']?[^\"\'>]*[\"\']?\s*>\s*</a>\s*)?"
+                     r"\*\*(BRD-\d+)\*\*\s*[—:-]+\s*(.*)$", lines[i])
         if m and m.group(1) not in nfr_ids:
             rid, rest = m.group(1), m.group(2)
             title = re.split(r"\s*(?:\.\s+\*|\s\*Screen|\s·\s\*|\s\*Mockup)", rest, 1)[0].strip().rstrip(".")
@@ -218,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-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"