@techierathore/techieflow 1.0.0

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

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# tf-render-html.sh — render framework Markdown docs to the shared HTML shell.
+#
+#   bash .tfcore/utils/tf-render-html.sh docs/MyApp-BRD.md [more.md ...]
+#   bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md --quiet
+#
+# Writes a sibling <file>.html for each input, implementing
+# .tfcore/templates/v4custom/html-render-shell.md — which stays the SPEC: the
+# CSS (§2), theme script (§3) and JS (§7) are extracted from it at render time,
+# so the shell can never drift from its own documentation.
+#
+# Thin wrapper over tf-render-html.py, matching the tf-emit.sh / tf-perf.sh
+# invocation idiom. Python 3 standard library only — no pandoc, no node, no pip.
+#
+# Exit: 0 rendered · 1 a render failed · 2 refused (checklist / spec missing)
+#
+# NOTE: checklists are NEVER rendered (html-render-shell §0). Passing a
+# *-Checklist.md is refused, not silently skipped.
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-render-html: python3 is required (standard library only)." >&2
+  exit 1
+fi
+
+exec python3 "$SELF_DIR/tf-render-html.py" "$@"

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

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# tf-routing-bind.sh — emit (or remove) the harness bindings declared by
+# .tfcore/routing.yaml (docs/Adapter-Design.md §5.3/§5.4; DECISIONS.md 2026-08-20).
+#
+# WHAT IT GENERATES when routing.yaml says `enabled: true`:
+#   Claude Code (§5.3):
+#     .claude/commands/tf/<phase>.md    — routed wrapper commands (/tf:<phase>),
+#                                         frontmatter model:+effort: from the tier
+#     .claude/agents/{tf-builder,tf-test-writer,tf-explorer,trblazeui,techierag}.md
+#                                       — tier-bound subagents
+#   OpenCode (§5.4):
+#     .opencode/opencode.json           — pure-JSON binding file loaded ALONGSIDE
+#                                         .opencode/opencode.jsonc; deep-merges
+#                                         model onto the existing agents/commands
+#                                         (verified against OpenCode 1.18.18:
+#                                         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
+# the manifest .tfcore/.session/routing-bind.manifest (gitignored) — the script
+# never deletes anything it did not generate. Run it after editing routing.yaml.
+# update-framework.sh runs it automatically in each app.
+#
+# Fail-soft: exits 0 unless the target is not a TechieFlow repo. Routing is
+# declared and OBSERVED (runs.jsonl model/tier/routed) — never enforced.
+
+set +e
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${1:-$(bash "$SELF_DIR/tf-harness.sh" root)}"
+ROOT="$(cd "$ROOT" 2>/dev/null && pwd)"
+[[ -n "$ROOT" && -d "$ROOT/.tfcore" ]] || { echo "tf-routing-bind: not a TechieFlow repo: ${ROOT:-<none>}" >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "tf-routing-bind: python3 required" >&2; exit 0; }
+
+python3 - "$ROOT" <<'PY'
+import json, os, re, sys
+
+root = sys.argv[1]
+ryaml = os.path.join(root, ".tfcore", "routing.yaml")
+manifest_path = os.path.join(root, ".tfcore", ".session", "routing-bind.manifest")
+
+# --- parse routing.yaml (flat format — see its header) --------------------
+cfg = {"enabled": False, "phases": {}, "subagents": {}, "tiers": {}, "effort": {}}
+sect = tier = None
+try:
+    for line in open(ryaml, encoding="utf-8"):
+        line = line.rstrip("\n")
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if not line.startswith(" "):
+            key, _, val = line.partition(":")
+            sect, tier = key.strip(), None
+            if sect == "enabled":
+                cfg["enabled"] = val.strip() == "true"
+        elif sect == "tiers":
+            if re.match(r"^  [a-z-]+:\s*$", line):
+                tier = line.strip()[:-1]
+                cfg["tiers"][tier] = {}
+            elif tier and line.startswith("    "):
+                k, _, v = line.strip().partition(":")
+                cfg["tiers"][tier][k.strip()] = v.strip()
+        elif sect in ("phases", "subagents", "effort"):
+            k, _, v = line.strip().partition(":")
+            cfg[sect][k.strip()] = v.strip()
+except FileNotFoundError:
+    pass  # no routing.yaml -> treat as disabled
+
+def model_for(t, harness):
+    return cfg["tiers"].get(t, {}).get(harness)
+
+# --- remove previously generated artifacts (manifest-driven) --------------
+removed = 0
+try:
+    for p in open(manifest_path, encoding="utf-8").read().splitlines():
+        p = p.strip()
+        if not p or ".." in p:
+            continue
+        fp = os.path.join(root, p)
+        if os.path.isfile(fp):
+            os.remove(fp)
+            removed += 1
+    os.remove(manifest_path)
+except FileNotFoundError:
+    pass
+# prune empty generated dirs
+for d in (os.path.join(root, ".claude", "commands", "tf"),):
+    try:
+        os.rmdir(d)
+    except OSError:
+        pass
+
+if not cfg["enabled"]:
+    print("tf-routing-bind: routing disabled — %d generated artifact(s) removed, nothing emitted" % removed)
+    raise SystemExit(0)
+
+generated = []
+
+def write(relpath, content):
+    fp = os.path.join(root, relpath)
+    os.makedirs(os.path.dirname(fp), exist_ok=True)
+    with open(fp, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(content)
+    generated.append(relpath)
+
+MARK = "<!-- generated by tf-routing-bind.sh from .tfcore/routing.yaml — do not edit; edit routing.yaml and re-run -->"
+
+# --- Claude Code: routed wrapper commands ---------------------------------
+OWNER = {"day1-greenfield": "analyst", "day1-brownfield": "analyst",
+         "author-brd": "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")
+    if t == "inherit" or not m:
+        continue
+    owner = OWNER.get(phase, "flow-master")
+    eff = cfg["effort"].get(t)
+    fm = ["---",
+          "description: Routed TechieFlow phase — %s on the %s tier" % (phase, t),
+          "model: %s" % m]
+    if eff:
+        fm.append("effort: %s" % eff)
+    fm.append("---")
+    body = ("%s\n%s\n\nLoad `.tfcore/agents/%s.md` and adopt its core principles "
+            "(git ban, smoke policy, status gate) without printing the greeting. "
+            "Then execute `.tfcore/tasks/%s.md` with arguments: $ARGUMENTS\n"
+            % ("\n".join(fm), MARK, owner, phase))
+    write(os.path.join(".claude", "commands", "tf", phase + ".md"), body)
+
+# --- Claude Code: tier-bound subagents ------------------------------------
+SUB_BODY = {
+    "tf-builder": ("Builds ONE REQ cluster (FN/NFR) to the project's coding standards. "
+        "Read `.tfcore/tasks/_smoke-test-policy.md` first. Hard rules: NEVER run git/gh; "
+        "smoke your changed feature yourself before returning; tag work with its [REQ-*] id "
+        "in the checklist Remarks; return { reqsImplemented[], filesChanged[], libraryIssues[] }."),
+    "tf-test-writer": ("Writes verification tests for one REQ cluster (verify-phase §4). "
+        "Black-box: never touch application source. NEVER run git/gh. "
+        "Return { testsAdded[], testsRefreshed[], unobservable[] }."),
+    "tf-explorer": ("Read-only codebase scan (devguide OBSERVE, index-docs). Never edits, "
+        "never runs git/gh. Returns findings as structured text."),
+    "trblazeui": ("Read the NuGet-deployed TrBlazeUI persona and fully adopt it. Resolve it in this "
+        "order and use the FIRST that exists: `.claude/commands/trblazeui.md` (current deploy target), "
+        "`.claude/trblazeui.md` (legacy deploy target), `.trblazeui/TrBlazeUI-AI-Reference.md` "
+        "(packaged component reference). Only if NONE exists, report that TrBlazeUI is not deployed "
+        "(`dotnet build` the app to unpack the package) and stop."),
+    "techierag": ("Read the NuGet-deployed TechieRag persona and fully adopt it. Resolve it in this "
+        "order and use the FIRST that exists: `.claude/commands/techierag.md` (current deploy target), "
+        "`.claude/techierag.md` (legacy deploy target), `.techierag/TechieRag-AI-Reference.md` "
+        "(packaged service reference). Only if NONE exists, report that TechieRag is not deployed "
+        "(`dotnet build` the app to unpack the package) and stop."),
+}
+DESC = {
+    "tf-builder": "TechieFlow FN/NFR cluster builder (routed tier)",
+    "tf-test-writer": "TechieFlow verify-phase test writer (routed tier)",
+    "tf-explorer": "TechieFlow read-only explorer (routed tier)",
+    "trblazeui": "TrBlazeUI UI builder persona (routed tier wrapper)",
+    "techierag": "TechieRag RAG builder persona (routed tier wrapper)",
+}
+for name, t in sorted(cfg["subagents"].items()):
+    m = model_for(t, "claude")
+    if t == "inherit" or not m or name not in SUB_BODY:
+        continue
+    body = ("---\nname: %s\ndescription: %s\nmodel: %s\n---\n%s\n%s\n"
+            % (name, DESC[name], m, MARK, SUB_BODY[name]))
+    write(os.path.join(".claude", "agents", name + ".md"), body)
+
+# --- OpenCode: pure-JSON binding file -------------------------------------
+oc = {"$schema": "https://opencode.ai/config.json", "agent": {}, "command": {}}
+PERSONA_TIER = {
+    "flow-master": cfg["phases"].get("build-phase"),
+    "flow-analyst": cfg["phases"].get("day1-greenfield"),
+    "flow-architect": cfg["phases"].get("day1-greenfield"),
+    "flow-verifier": cfg["phases"].get("verify-phase"),
+}
+for name, t in PERSONA_TIER.items():
+    m = model_for(t, "opencode") if t else None
+    if m and t != "inherit":
+        oc["agent"][name] = {"model": m}
+for name, t in sorted(cfg["subagents"].items()):
+    m = model_for(t, "opencode")
+    if t == "inherit" or not m:
+        continue
+    if name in ("trblazeui", "techierag"):
+        oc["agent"][name] = {"model": m}  # registered in opencode.jsonc; merge model on
+    else:
+        oc["agent"][name] = {  # new subagents: entries must validate standalone
+            "description": DESC.get(name, name),
+            "mode": "subagent",
+            "model": m,
+            "prompt": SUB_BODY.get(name, name),
+        }
+for phase, t in sorted(cfg["phases"].items()):
+    m = model_for(t, "opencode")
+    if t == "inherit" or not m:
+        continue
+    oc["command"]["techieflow:tasks:" + phase] = {  # complete entry: files validate standalone
+        "template": "{file:../.tfcore/tasks/%s.md}" % phase,
+        "description": "Routed: %s (%s tier)" % (phase, t),
+        "model": m,
+    }
+write(os.path.join(".opencode", "opencode.json"),
+      json.dumps(oc, indent=2, ensure_ascii=False) + "\n")
+
+# --- manifest -------------------------------------------------------------
+os.makedirs(os.path.dirname(manifest_path), exist_ok=True)
+with open(manifest_path, "w", encoding="utf-8", newline="\n") as fh:
+    fh.write("\n".join(generated) + "\n")
+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

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# tf-routing.sh — the ONE command for model routing. Run it from an app repo.
+#
+#   bash .tfcore/utils/tf-routing.sh status                     what is routing doing right now?
+#   bash .tfcore/utils/tf-routing.sh on                         turn routing ON  (generates all bindings)
+#   bash .tfcore/utils/tf-routing.sh off                        turn routing OFF (removes all bindings)
+#   bash .tfcore/utils/tf-routing.sh set-tier  <phase> <tier>   e.g. set-tier verify-phase economy
+#   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
+#   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
+#                                                               ADVISORY: "after <attempts> runs of <phase> on the same
+#                                                               REQs, launch the next one on <tier>" — you apply it at
+#                                                               launch; nothing switches a running phase's model.
+#
+# Everything edits .tfcore/routing.yaml in place (comments preserved) and then
+# regenerates the harness bindings automatically via tf-routing-bind.sh — you
+# never have to touch the generated files. Design: docs/Adapter-Design.md §5;
+# owner guide: README §17b / WORKFLOW.html §17b.
+
+set +e
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(bash "$SELF_DIR/tf-harness.sh" root)"
+RY="$ROOT/.tfcore/routing.yaml"
+CMD="${1:-status}"
+
+[[ -f "$RY" ]] || { echo "No .tfcore/routing.yaml here ($ROOT) — run update-framework.sh first." >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "python3 required" >&2; exit 1; }
+
+_bind() { bash "$SELF_DIR/tf-routing-bind.sh" "$ROOT"; }
+
+case "$CMD" in
+  on)
+    python3 - "$RY" <<'PY'
+import sys, re
+p = sys.argv[1]; s = open(p, encoding="utf-8").read()
+s2 = re.sub(r"^enabled:.*$", "enabled: true", s, count=1, flags=re.M)
+open(p, "w", encoding="utf-8", newline="\n").write(s2)
+PY
+    echo "routing: ENABLED in $RY"
+    _bind
+    echo "Check with: bash .tfcore/utils/tf-routing.sh status"
+    ;;
+  off)
+    python3 - "$RY" <<'PY'
+import sys, re
+p = sys.argv[1]; s = open(p, encoding="utf-8").read()
+s2 = re.sub(r"^enabled:.*$", "enabled: false", s, count=1, flags=re.M)
+open(p, "w", encoding="utf-8", newline="\n").write(s2)
+PY
+    echo "routing: DISABLED in $RY"
+    _bind
+    ;;
+  bind)
+    _bind
+    ;;
+  set-tier)
+    NAME="${2:-}"; TIER="${3:-}"
+    case "$TIER" in frontier|standard|economy|inherit) ;; *)
+      echo "usage: tf-routing.sh set-tier <phase-or-subagent> <frontier|standard|economy|inherit>" >&2; exit 2 ;;
+    esac
+    [[ -n "$NAME" ]] || { echo "usage: tf-routing.sh set-tier <phase-or-subagent> <tier>" >&2; exit 2; }
+    python3 - "$RY" "$NAME" "$TIER" <<'PY'
+import sys
+p, name, tier = sys.argv[1:4]
+lines = open(p, encoding="utf-8").read().splitlines(True)
+sect = None; done = False
+for i, line in enumerate(lines):
+    if line.strip() and not line.startswith(" ") and not line.lstrip().startswith("#"):
+        sect = line.split(":")[0].strip()
+    elif sect in ("phases", "subagents") and line.strip().startswith(name + ":"):
+        lines[i] = "  %s: %s\n" % (name, tier)
+        done = True
+        break
+if not done:
+    # unknown name: add it under phases (most common case)
+    for i, line in enumerate(lines):
+        if line.startswith("phases:"):
+            lines.insert(i + 1, "  %s: %s\n" % (name, tier))
+            done = True
+            break
+open(p, "w", encoding="utf-8", newline="\n").write("".join(lines))
+print(("set %s -> %s" % (name, tier)) if done else "FAILED: no phases: section found")
+PY
+    _bind
+    ;;
+  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 ;;
+    esac
+    case "$HARNESS" in claude|opencode|codex) ;; *)
+      echo "harness must be claude, opencode, or codex" >&2; exit 2 ;;
+    esac
+    [[ -n "$MODEL" ]] || { echo "usage: tf-routing.sh set-model <tier> <claude|opencode|codex> <model-id>" >&2; exit 2; }
+    python3 - "$RY" "$TIER" "$HARNESS" "$MODEL" <<'PY'
+import sys
+p, tier, harness, model = sys.argv[1:5]
+lines = open(p, encoding="utf-8").read().splitlines(True)
+in_tiers = in_tier = False; done = False
+for i, line in enumerate(lines):
+    if line.strip() and not line.startswith(" ") and not line.lstrip().startswith("#"):
+        in_tiers = line.startswith("tiers:")
+        in_tier = False
+    elif in_tiers and line.startswith("  ") and not line.startswith("    ") and line.strip().rstrip(":"):
+        in_tier = line.strip().rstrip(":") == tier
+    elif in_tiers and in_tier and line.strip().startswith(harness + ":"):
+        lines[i] = "    %s: %s\n" % (harness, model)
+        done = True
+        break
+open(p, "w", encoding="utf-8", newline="\n").write("".join(lines))
+print(("set tiers.%s.%s -> %s" % (tier, harness, model)) if done else "FAILED: tier '%s' / key '%s' not found in tiers: map" % (tier, harness))
+PY
+    _bind
+    ;;
+  set-escalation)
+    PHASE="${2:-}"; ATTEMPTS="${3:-}"; TIER="${4:-}"
+    [[ -n "$PHASE" ]] || { echo "usage: tf-routing.sh set-escalation <phase> <attempts> <frontier|standard|economy>" >&2; exit 2; }
+    [[ "$ATTEMPTS" =~ ^[1-9][0-9]*$ ]] || { echo "attempts must be a positive integer (e.g. 2)" >&2; exit 2; }
+    case "$TIER" in frontier|standard|economy) ;; *)
+      echo "usage: tf-routing.sh set-escalation <phase> <attempts> <frontier|standard|economy>" >&2; exit 2 ;;
+    esac
+    python3 - "$RY" "$PHASE" "$ATTEMPTS" "$TIER" <<'PY'
+import sys
+p, phase, attempts, tier = sys.argv[1:5]
+lines = open(p, encoding="utf-8").read().splitlines(True)
+block = ["  %s:\n" % phase, "    after_attempts: %s\n" % attempts, "    tier: %s\n" % tier]
+sect = None; start = end = None; esc_at = None
+for i, line in enumerate(lines):
+    if line.strip() and not line.startswith(" ") and not line.lstrip().startswith("#"):
+        if sect == "escalation" and start is not None and end is None:
+            end = i
+        sect = line.split(":")[0].strip()
+        if sect == "escalation":
+            esc_at = i
+    elif sect == "escalation":
+        if line.startswith("  ") and not line.startswith("    ") and line.strip().rstrip(":") == phase:
+            start = i
+        elif start is not None and end is None and line.startswith("  ") and not line.startswith("    "):
+            end = i
+if start is not None:
+    # replace the existing <phase> block (its 2-space header + 4-space children)
+    if end is None:
+        end = len(lines)
+        while end > start + 1 and not lines[end - 1].strip():
+            end -= 1
+    lines[start:end] = block
+    what = "updated"
+elif esc_at is not None:
+    lines[esc_at + 1:esc_at + 1] = block
+    what = "added"
+else:
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    lines += ["\n", "# Advisory escalation — see DECISIONS.md 2026-08-21.\n", "escalation:\n"] + block
+    what = "added (new escalation: section)"
+open(p, "w", encoding="utf-8", newline="\n").write("".join(lines))
+print("escalation.%s %s -> after_attempts: %s, tier: %s (advisory — applied at launch, never mid-run)" % (phase, what, attempts, tier))
+PY
+    # No _bind: escalation is advisory and generates no harness binding.
+    ;;
+  status)
+    python3 - "$RY" "$ROOT" <<'PY'
+import sys, os, re
+p, root = sys.argv[1], sys.argv[2]
+cfg = {"enabled": False, "phases": {}, "subagents": {}, "tiers": {}, "effort": {}, "escalation": {}}
+sect = tier = None
+for line in open(p, encoding="utf-8"):
+    line = line.rstrip("\n")
+    if not line.strip() or line.lstrip().startswith("#"):
+        continue
+    if not line.startswith(" "):
+        key, _, val = line.partition(":")
+        sect, tier = key.strip(), None
+        if sect == "enabled":
+            cfg["enabled"] = val.strip() == "true"
+    elif sect in ("tiers", "escalation"):
+        if re.match(r"^  [a-z0-9-]+:\s*$", line):
+            tier = line.strip()[:-1]; cfg[sect][tier] = {}
+        elif tier and line.startswith("    "):
+            k, _, v = line.strip().partition(":")
+            cfg[sect][tier][k.strip()] = v.strip()
+    elif sect in ("phases", "subagents", "effort"):
+        k, _, v = line.strip().partition(":")
+        cfg[sect][k.strip()] = v.strip()
+
+manifest = os.path.join(root, ".tfcore", ".session", "routing-bind.manifest")
+bound = os.path.isfile(manifest)
+n_art = sum(1 for l in open(manifest)) if bound else 0
+
+print("Routing: %s   (bindings on disk: %s)" % ("ON" if cfg["enabled"] else "OFF",
+      "%d generated artifacts" % n_art if bound else "none"))
+if cfg["enabled"] != bound:
+    print("  !! flag and bindings disagree — run: bash .tfcore/utils/tf-routing.sh bind")
+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()
+print("Phases by tier:")
+for t in ("frontier", "standard", "economy", "inherit"):
+    ph = sorted(k for k, v in cfg["phases"].items() if v == t)
+    if ph:
+        print("  %-9s %s" % (t, ", ".join(ph)))
+sub = ["%s=%s" % (k, v) for k, v in sorted(cfg["subagents"].items())]
+if sub:
+    print("Subagents:  " + ", ".join(sub))
+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"]):
+        e = cfg["escalation"][ph]
+        n, t = e.get("after_attempts", "?"), e.get("tier", "?")
+        base = cfg["phases"].get(ph, "inherit")
+        print("  %-18s after %s attempt(s) on the same REQs -> launch the next on %s (base tier: %s)" % (ph, n, t, base))
+    print("  next attempt number: bash .tfcore/utils/tf-emit.sh --next-run-attempt <phase> <REQ-ID>...")
+    print("  change:              bash .tfcore/utils/tf-routing.sh set-escalation <phase> <attempts> <tier>")
+else:
+    print("  none declared — add one: bash .tfcore/utils/tf-routing.sh set-escalation fix-issues 2 frontier")
+print()
+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:")
+    print("  1. you run a /techieflow:tasks:* command  -> the run executes on the tier model (footer)")
+    print("  2. you Tab to a persona (flow-master, flow-verifier, ...) -> each carries its bound model")
+    print("  3. a phase finishes -> docs/metrics/*.jsonl records tier, observed model, routed, cost")
+    print("NOTE (verified): in the TUI a routed command's model STAYS for the session afterwards —")
+    print("pick your model from the model list (or start a new session) if you keep chatting.")
+else:
+    print("Turn on with:  bash .tfcore/utils/tf-routing.sh on")
+PY
+    ;;
+  *)
+    sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'
+    exit 2
+    ;;
+esac
+exit 0

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# tf-yolo.sh — YOLO / goal-mode state for TechieFlow (rule: .tfcore/tasks/_yolo-mode.md)
+#
+#   bash .tfcore/utils/tf-yolo.sh on [--source <who>] [--goal "<text>"]   turn YOLO on
+#   bash .tfcore/utils/tf-yolo.sh off                                     turn YOLO off
+#   bash .tfcore/utils/tf-yolo.sh status                                  print ON/OFF + details (exit 0 always)
+#   bash .tfcore/utils/tf-yolo.sh is-on                                   exit 0 if ON, 1 if OFF (for scripts/hooks)
+#   bash .tfcore/utils/tf-yolo.sh done [complete|blocked] ["<summary>"]   goal finished → write the sentinel
+#                                                                         the tf-goal.sh supervisor stops on
+#   bash .tfcore/utils/tf-yolo.sh clear-done                              remove the sentinel (supervisor does this)
+#
+# YOLO is ON when ANY of these holds (checked in this order by block-git.sh too):
+#   1. env TF_YOLO=1                      (tf-goal.sh exports it for the whole run)
+#   2. .tfcore/.session/yolo.json exists (written by `on`; the agent writes it on *yolo / a goal)
+#   3. the harness itself is in bypass mode (Claude Code permission_mode=bypassPermissions —
+#      only the hook can see that; this script cannot)
+#
+# State lives under .tfcore/.session/ — gitignored in the framework repo and, in
+# consumer apps, inside the ignored .tfcore/ block. Nothing here is ever committed.
+#
+# NO VETO: this script never fails a phase. Every path exits 0 except `is-on`,
+# whose non-zero exit is its answer, not an error.
+
+set -u
+
+ROOT="${CLAUDE_PROJECT_DIR:-${TF_PROJECT_DIR:-}}"
+if [[ -z "$ROOT" ]]; then
+  # walk up from cwd to the nearest .tfcore/
+  d="$PWD"
+  while [[ "$d" != "/" ]]; do
+    if [[ -d "$d/.tfcore" ]]; then ROOT="$d"; break; fi
+    d="$(dirname "$d")"
+  done
+fi
+ROOT="${ROOT:-$PWD}"
+STATE_DIR="$ROOT/.tfcore/.session"
+FLAG="$STATE_DIR/yolo.json"
+DONE="$STATE_DIR/goal-done.json"
+
+now_utc() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+# A flag nobody turned off EXPIRES. `off` and `done` clear it, but a session that
+# is killed, crashes, or simply ends without the sentinel leaves it behind, and an
+# unnoticed flag silently grants unprompted deletes for as long as it sits there
+# (found on five repos, one of them 6 days old, 2026-08-28). Age is taken from the
+# file's mtime via `find -mmin`, which behaves the same on GNU and BSD — parsing
+# the ISO `since` field would need `date -d`, which does not exist on macOS.
+# Override with TF_YOLO_TTL_HOURS; 0 disables expiry. tf-goal.sh is unaffected —
+# it exports TF_YOLO=1, which is checked first and never expires mid-run.
+TTL_HOURS="${TF_YOLO_TTL_HOURS:-24}"
+flag_live() {  # exit 0 = flag present AND not expired
+  [[ -f "$FLAG" ]] || return 1
+  [[ "$TTL_HOURS" == "0" ]] && return 0
+  [[ -n "$(find "$FLAG" -mmin "+$(( TTL_HOURS * 60 ))" 2>/dev/null)" ]] && return 1
+  return 0
+}
+json_escape() { printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' 2>/dev/null || printf '"%s"' "${1//\"/\\\"}"; }
+
+cmd="${1:-status}"; shift || true
+
+case "$cmd" in
+  on)
+    SOURCE="agent"; GOAL=""
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --source) SOURCE="${2:-agent}"; shift 2 ;;
+        --goal) GOAL="${2:-}"; shift 2 ;;
+        *) shift ;;
+      esac
+    done
+    mkdir -p "$STATE_DIR" 2>/dev/null || true
+    {
+      printf '{"on":true,"since":"%s","source":%s,"goal":%s,"harness":%s}\n' \
+        "$(now_utc)" "$(json_escape "$SOURCE")" "$(json_escape "$GOAL")" "$(json_escape "${TF_HARNESS:-claude-code}")"
+    } > "$FLAG" 2>/dev/null || true
+    rm -f "$DONE" 2>/dev/null || true
+    echo "YOLO: ON (source=$SOURCE) — no confirmations; deletes + read-only git allowed; git WRITES still blocked; run to completion."
+    ;;
+  off)
+    rm -f "$FLAG" 2>/dev/null || true
+    echo "YOLO: OFF — back to ask-on-delete, no-git, confirm-at-phase-boundaries."
+    ;;
+  is-on)
+    if [[ "${TF_YOLO:-0}" == "1" ]] || flag_live; then exit 0; else exit 1; fi
+    ;;
+  status)
+    if [[ "${TF_YOLO:-0}" == "1" ]]; then
+      echo "YOLO: ON (env TF_YOLO=1)"
+    elif flag_live; then
+      echo "YOLO: ON ($(cat "$FLAG" 2>/dev/null))"
+    elif [[ -f "$FLAG" ]]; then
+      echo "YOLO: OFF (flag EXPIRED after ${TTL_HOURS}h and is ignored — $(cat "$FLAG" 2>/dev/null)). Run 'tf-yolo.sh off' to delete it, or 'on' to start a fresh window."
+    else
+      echo "YOLO: OFF"
+    fi
+    if [[ -f "$DONE" ]]; then echo "GOAL-DONE: $(cat "$DONE" 2>/dev/null)"; fi
+    ;;
+  done)
+    OUTCOME="${1:-complete}"; SUMMARY="${2:-}"
+    case "$OUTCOME" in complete|blocked) ;; *) SUMMARY="$OUTCOME $SUMMARY"; OUTCOME="complete" ;; esac
+    mkdir -p "$STATE_DIR" 2>/dev/null || true
+    printf '{"outcome":%s,"summary":%s,"ts":"%s"}\n' \
+      "$(json_escape "$OUTCOME")" "$(json_escape "$SUMMARY")" "$(now_utc)" > "$DONE" 2>/dev/null || true
+    # The grant ENDS WITH THE GOAL. Until 2026-08-28 `done` left the flag in place,
+    # so even the well-behaved path — the one _yolo-mode.md §Completion prescribes as
+    # the last action of every run — left the repo permanently in YOLO, with deletes
+    # unprompted and read-only git open and nothing on screen saying so. The
+    # supervisor reads $DONE, never $FLAG, so clearing it here stops nothing.
+    rm -f "$FLAG" 2>/dev/null || true
+    echo "GOAL-DONE ($OUTCOME) recorded at $DONE — the supervisor (tf-goal.sh) will stop. YOLO flag cleared."
+    ;;
+  clear-done)
+    rm -f "$DONE" 2>/dev/null || true
+    ;;
+  *)
+    echo "usage: tf-yolo.sh on|off|status|is-on|done [complete|blocked] [summary]|clear-done" >&2
+    ;;
+esac
+exit 0