@techierathore/techieflow 1.0.2 → 1.0.4

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# tf-phase.sh — mark which TechieFlow command is running (Sitting 4b, 2026-09-05).
+#
+#   bash .tfcore/utils/tf-phase.sh start <command> [App]   # step 0 of every task: prints the start
+#                                                          # time and writes the marker
+#   bash .tfcore/utils/tf-phase.sh show                    # prints the marker, or "none"
+#   bash .tfcore/utils/tf-phase.sh end                     # removes the marker
+#   bash .tfcore/utils/tf-phase.sh goal [App]              # tf-goal.sh only: an unclaimed marker the first
+#                                                          # command's `start` claims, keeping its started
+#
+# The marker is .tfcore/.session/phase.json:
+#   {"cmd":"build-phase","app":"MyApp","started":"2026-09-05T16:19:38Z"}
+# Who reads it:
+#   - .tfcore/hooks/guard-db.sh: a migration runner is allowed only while the marker says
+#     build-phase or fix-issues (MISS-TechieFlow-20260905-09: day-1 patched a database).
+#   - tf-emit.sh: a run record that leaves `started` out gets it from here, so the start
+#     time is a measurement, never reconstructed.
+# A marker older than 24 h is ignored by the readers (a killed session must not keep a
+# grant alive). The next `start` overwrites; `end` is optional tidiness.
+# Never committed: .tfcore/.session/ is git-ignored. Exit 0 always except a usage error (2).
+set -u
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DIR="$ROOT/.tfcore/.session"
+FILE="$DIR/phase.json"
+case "${1:-}" in
+  start)
+    CMD="${2:-}"
+    [[ -z "$CMD" ]] && { echo "tf-phase: usage: tf-phase.sh start <command> [App]" >&2; exit 2; }
+    CMD="${CMD#\*}"
+    APP="${3:-}"
+    NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    mkdir -p "$DIR"
+    # A supervisor (tf-goal.sh) writes an unclaimed marker {"cmd":"goal",…} when its first cycle
+    # starts. The first command of that run claims it and KEEPS its started: the run began when
+    # the harness began reading, not when the agent got round to step 0 (MISS-TechieFlow-20260905-20:
+    # a 38-minute stage 2 recorded a 27-second run because step 0 ran last).
+    if [[ -f "$FILE" ]] && grep -q '"cmd":"goal"' "$FILE" && [[ -z "$(find "$FILE" -mmin +1440 2>/dev/null)" ]]; then
+      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"
+    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
+    # status file already carry when the command starts are recorded, so the gate and the Stop
+    # hook block only on findings this command introduces (Schemas §7.1 decision 8: old projects
+    # are repaired through *amend-docs, never by whichever command happens to run next).
+    if [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+      docs=(); for f in "$ROOT"/docs/*-Checklist.md "$ROOT"/PROJECT-STATUS.md; do [[ -f "$f" ]] && docs+=("$f"); done
+      if [[ ${#docs[@]} -gt 0 ]]; then
+        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write "${docs[@]}" 2>/dev/null | tail -1 >&2 ) || true
+      fi
+    fi
+    # The framework's own scripts, against THIS project's real files, before the command
+    # does anything (2026-09-09). Nine framework defects reached TfLens by being met
+    # mid-build, and each cost a switch to the framework repo and back. Step 0 is the one
+    # place every command already passes through, so the check lives here and no task file
+    # has to mention it -- including commands added later.
+    #
+    # It NEVER blocks: a framework defect is reported and the command carries on, exactly
+    # as a library gap does. Set TF_SKIP_SELFCHECK=1 to skip it (the self-tests do).
+    if [[ "${TF_SKIP_SELFCHECK:-0}" != "1" && -f "$ROOT/.tfcore/utils/tf-selfcheck.sh" ]]; then
+      sc="$(cd "$ROOT" && bash .tfcore/utils/tf-selfcheck.sh 2>/dev/null)" || true
+      if grep -q '^FAIL' <<<"$sc"; then
+        echo "tf-phase: the framework is broken on this project — log these in the feedback file and carry on:" >&2
+        grep '^FAIL' <<<"$sc" >&2
+        echo "tf-phase: entries to paste: bash .tfcore/utils/tf-selfcheck.sh --report" >&2
+      else
+        echo "tf-phase: framework self-check clean" >&2
+      fi
+    fi
+    ;;
+  goal)
+    # written by tf-goal.sh at the start of a run's first cycle; claimed by the first `start`
+    NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    mkdir -p "$DIR"
+    printf '{"cmd":"goal","app":"%s","started":"%s"}\n' "${2:-}" "$NOW" > "$FILE"
+    echo "$NOW"
+    ;;
+  show)
+    if [[ -f "$FILE" ]]; then cat "$FILE"; else echo "none"; fi
+    ;;
+  end)
+    rm -f "$FILE"
+    echo "tf-phase: marker removed"
+    ;;
+  *)
+    sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 2
+    ;;
+esac
+exit 0

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

@@ -479,6 +479,22 @@ def is_requirements_checklist(base, raw):
                 or "SINGLE SOURCE OF TRUTH" in head)
 
 
+def is_miss_list(base, raw):
+    """Is this THE derived miss log, or an ordinary document about misses?
+
+    `docs/{AppName}-Misses.md` is rebuilt from `misses.jsonl` on every write and is
+    read by agents and by the owner in markdown. Rendering it produced an HTML copy
+    nobody opened, re-rendered on every miss, in every project — 20 of them across
+    the estate before this refusal existed (owner, 2026-09-08).
+
+    Identify the document, do not guess from the suffix, exactly as the checklist
+    rule does: the name must match AND the content must carry the generator's own
+    Source row. A hand-written note called `Release-Misses.md` has neither."""
+    if not re.search(r"-Misses\.md$", base, re.I):
+        return False
+    return "Rewritten by `tf-misses-md.sh`" in raw[:2000]
+
+
 NEXT_CMD_H2 = re.compile(r"^##\s+Next command to run\s*$", re.I)
 
 
@@ -541,6 +557,10 @@ def render(md_path, css, head_js, body_js, out_dir=None):
         raise Refused("%s is the requirements checklist — checklists are AI-agent "
                       "working documents and are NEVER rendered to HTML "
                       "(html-render-shell §0)." % base)
+    if is_miss_list(base, raw_probe):
+        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)
 
     raw = raw_probe
     lines = raw.split("\n")

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

@@ -16,9 +16,6 @@
 #                                         model-only agent entries merge, command
 #                                         entries must be complete → they carry
 #                                         template+description+model)
-#   Codex:
-#     .codex/agents/*.toml + .agents/skills/techieflow-*/SKILL.md, generated
-#     by tf-codex-bind.py. Subagent model/effort is pinned when routing is on;
 #     skills remain thin loaders and do not claim to switch the main thread.
 #
 # When `enabled: false` (the default) every generated artifact is REMOVED, using
@@ -44,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
@@ -70,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
@@ -109,9 +192,18 @@ def write(relpath, content):
 
 MARK = "<!-- generated by tf-routing-bind.sh from .tfcore/routing.yaml — do not edit; edit routing.yaml and re-run -->"
 
+# A phase whose task file no longer ships gets no binding, with a printed warning: the seven
+# never-used commands were removed in Sitting 4c (2026-09-06) and routing.yaml is preserved per
+# project, so a stale line there must never write a file reference OpenCode refuses to load
+# (MISS-TechieFlow-20260906-27: OpenCode would not start on TechieBlog-oc).
+for _ph in sorted(cfg["phases"]):
+    if not os.path.isfile(os.path.join(root, ".tfcore", "tasks", _ph + ".md")):
+        print("tf-routing-bind: phase %s has no task file .tfcore/tasks/%s.md; no binding written (remove the line from routing.yaml)" % (_ph, _ph))
+        del cfg["phases"][_ph]
+
 # --- Claude Code: routed wrapper commands ---------------------------------
 OWNER = {"day1-greenfield": "analyst", "day1-brownfield": "analyst",
-         "author-brd": "analyst", "amend-docs": "analyst", "mockups": "analyst",
+         "amend-docs": "analyst", "mockups": "analyst",
          "split-brd": "analyst", "verify-phase": "verifier"}
 for phase, t in sorted(cfg["phases"].items()):
     m = model_for(t, "claude")
@@ -212,5 +304,4 @@ with open(manifest_path, "w", encoding="utf-8", newline="\n") as fh:
 print("tf-routing-bind: routing enabled — %d artifact(s) generated (%d stale removed)"
       % (len(generated), removed))
 PY
-python3 "$SELF_DIR/tf-codex-bind.py" "$ROOT" || echo "tf-routing-bind: warning: Codex bindings were not refreshed" >&2
 exit 0

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

@@ -8,7 +8,7 @@
 #   bash .tfcore/utils/tf-routing.sh set-model <tier> <harness> <model>
 #                                                               e.g. set-model economy opencode opencode-go/deepseek-v4-flash
 #                                                               e.g. set-model frontier claude opus
-#                                                               e.g. set-model standard codex gpt-5.6-terra
+#                                                               e.g. set-model standard opencode openai/gpt-5.6-terra
 #   bash .tfcore/utils/tf-routing.sh bind                       re-generate bindings after editing routing.yaml by hand
 #   bash .tfcore/utils/tf-routing.sh set-escalation <phase> <attempts> <tier>
 #                                                               e.g. set-escalation fix-issues 2 frontier
@@ -90,12 +90,12 @@ PY
   set-model)
     TIER="${2:-}"; HARNESS="${3:-}"; MODEL="${4:-}"
     case "$TIER" in frontier|standard|economy) ;; *)
-      echo "usage: tf-routing.sh set-model <frontier|standard|economy> <claude|opencode|codex> <model-id>" >&2; exit 2 ;;
+      echo "usage: tf-routing.sh set-model <frontier|standard|economy> <claude|opencode> <model-id>" >&2; exit 2 ;;
     esac
-    case "$HARNESS" in claude|opencode|codex) ;; *)
-      echo "harness must be claude, opencode, or codex" >&2; exit 2 ;;
+    case "$HARNESS" in claude|opencode) ;; *)
+      echo "harness must be claude or opencode" >&2; exit 2 ;;
     esac
-    [[ -n "$MODEL" ]] || { echo "usage: tf-routing.sh set-model <tier> <claude|opencode|codex> <model-id>" >&2; exit 2; }
+    [[ -n "$MODEL" ]] || { echo "usage: tf-routing.sh set-model <tier> <claude|opencode> <model-id>" >&2; exit 2; }
     python3 - "$RY" "$TIER" "$HARNESS" "$MODEL" <<'PY'
 import sys
 p, tier, harness, model = sys.argv[1:5]
@@ -199,7 +199,7 @@ print()
 print("Tier models:")
 for t in ("frontier", "standard", "economy"):
     m = cfg["tiers"].get(t, {})
-    print("  %-9s claude: %-10s opencode: %-36s codex: %s" % (t, m.get("claude", "-"), m.get("opencode", "-"), m.get("codex", "-")))
+    print("  %-9s claude: %-10s opencode: %s" % (t, m.get("claude", "-"), m.get("opencode", "-")))
 print()
 print("Phases by tier:")
 for t in ("frontier", "standard", "economy", "inherit"):
@@ -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"]):
@@ -226,7 +233,6 @@ if cfg["enabled"]:
     print("Invoke routed phases as:")
     print("  OpenCode:    /techieflow:tasks:<phase>        (same commands as always — model now pinned)")
     print("  Claude Code: /tf:<phase>                      (new wrappers; old commands still work, unrouted)")
-    print("  Codex:        $techieflow-<phase>              (main-thread model inherited; delegated roles are pinned)")
     print()
     print("WHERE YOU SEE IT — opening the TUI looks UNCHANGED on purpose: your normal chat")
     print("(the default 'build' agent) stays on YOUR selected model. Routing becomes visible when:")

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

@@ -0,0 +1,323 @@
+#!/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.
+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+) 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, total = m.group(1), *(int(x) for x in m.groups()[1:])
+    if work + term + blocked != 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),
+               "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)
+
+# ---- 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 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