@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/utils/tf-model-pick.sh

@@ -0,0 +1,475 @@
+#!/usr/bin/env bash
+# tf-model-pick.sh — which model should this tier run on RIGHT NOW, and how is it paid for.
+#
+# Two questions the framework could not answer before 2026-09-10, both found by the owner
+# (MISS-TechieFlow-20260910-01 and -02):
+#
+#   1. The tier model's usage limit is reached. What now?  ->  `pick` walks the tier's
+#      `fallbacks:` chain and returns the first model that is not on cooldown. tf-goal.sh puts
+#      the limited model on cooldown until its stated reset; tf-routing-bind.sh asks the same
+#      question when it writes the harness bindings, so the sub-agents move with the main agent.
+#
+#   2. What does a cost number from this model MEAN?  ->  `billing` says whether the model is
+#      paid for by a flat-fee subscription (marginal dollars are zero, count tokens), by a
+#      metered API key (the dollars are real money), or by nothing at all because it runs on
+#      this machine. tf-emit.sh stamps the answer on every run record so a report can never sum
+#      a subscription's zero into a money figure.
+#
+# USAGE
+#   tf-model-pick.sh pick <tier> [harness]        -> the model id to use now ("inherit" if none)
+#   tf-model-pick.sh chain <tier> [harness]       -> the whole ordered chain, one per line,
+#                                                    each marked ok | cooldown until <time>
+#   tf-model-pick.sh cooldown <harness> <model> <until> ["<why>"]
+#                                                 -> park a model. <until> is an epoch, or +<n>
+#                                                    minutes, or "probe" for the no-reset-time
+#                                                    case (parked for TF_MODEL_PROBE_MIN, 60m).
+#   tf-model-pick.sh clear [harness] [model]      -> unpark; no arguments clears everything
+#   tf-model-pick.sh status                       -> what every tier resolves to, and why
+#   tf-model-pick.sh billing <model> [harness]    -> mode<TAB>source<TAB>detail
+#   tf-model-pick.sh rate <model> [harness]       -> input<TAB>output<TAB>cache_read<TAB>cache_write
+#                                                    <TAB>source, in US$ per million tokens; exit 1
+#                                                    with no output when nothing prices the model
+#   tf-model-pick.sh was-limited <harness> <model> <epoch>
+#                                                 -> exit 0 if that model was on cooldown then
+#
+# WHERE THE COOLDOWN LIVES. Inside the project, at `.tfcore/.session/model-cooldown.json`, because
+# that is where TechieFlow itself lives: it is installed per project through npm/npx and never at
+# machine level, and the owner has to be able to change it for one project without touching
+# another (owner, 2026-09-10). `cooldown_file:` in routing.yaml moves it — an absolute path, or a
+# path relative to the project root — and TF_MODEL_HEALTH_FILE overrides both for a single run.
+#
+# The cost of keeping it per project, said plainly: a usage limit belongs to an account, so two
+# projects each discover the same limit for themselves, one wasted cycle apiece. Point them at one
+# shared `cooldown_file:` if you would rather they learned it from each other.
+#
+# Expired entries are kept for 30 days so tf-emit.sh can answer "was this run a fallback?" after
+# the fact, then pruned.
+#
+# Fail-soft everywhere: an unreadable file, a missing catalog, a provider nobody recognises — the
+# answer degrades to the tier model and to billing mode "unknown". Routing is declared and
+# observed, never enforced; this script keeps that property.
+
+set +e
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(bash "$SELF_DIR/tf-harness.sh" root)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-model-pick: python3 required" >&2; exit 0; }
+
+TF_MP_ROOT="$ROOT" python3 - "$@" <<'PY'
+import json, os, sys, time, datetime
+
+root = os.environ.get("TF_MP_ROOT") or os.getcwd()
+argv = sys.argv[1:]
+cmd = argv[0] if argv else "status"
+
+KEEP_DAYS = 30
+PROBE_MIN = int(os.environ.get("TF_MODEL_PROBE_MIN") or 60)
+LOCAL_PROVIDERS = ("lmstudio", "ollama", "llamacpp", "llama-cpp", "vllm", "localhost", "local")
+# A flat monthly fee whose usage is metered IN DOLLARS against a per-model allowance. OpenCode Go
+# is $10/month with a $15–$60 monthly limit per model and 5-hour / weekly / monthly thresholds
+# (https://opencode.ai/docs/go), so the dollars it reports are ALLOWANCE CONSUMED, not an invoice
+# — and they are the very numbers that produce the limit the fallback chain exists for. An API
+# key alone cannot tell you this; the provider name can, and `billing:` overrides it either way.
+PLAN_PROVIDERS = ("opencode-go",)
+
+
+def die(msg, code=2):
+    sys.stderr.write("tf-model-pick: %s\n" % msg)
+    raise SystemExit(code)
+
+
+def now():
+    return int(time.time())
+
+
+def iso(ep):
+    try:
+        return datetime.datetime.fromtimestamp(
+            int(ep), datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    except Exception:
+        return str(ep)
+
+
+# --- routing.yaml (the same flat two-space format every other reader uses) --
+def routing():
+    cfg = {"enabled": False, "tiers": {}, "fallbacks": {}, "billing": {}, "phases": {},
+           "cooldown_file": ""}
+    sect = tier = None
+    try:
+        for line in open(os.path.join(root, ".tfcore", "routing.yaml"), 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 == "cooldown_file":
+                    cfg["cooldown_file"] = val.strip()
+            elif sect in ("tiers", "fallbacks"):
+                if line.rstrip().endswith(":") and not line.startswith("    "):
+                    tier = line.strip()[:-1]
+                    cfg[sect].setdefault(tier, {})
+                elif tier and line.startswith("    "):
+                    k, _, v = line.strip().partition(":")
+                    cfg[sect][tier][k.strip()] = v.strip()
+            elif sect in ("billing", "phases"):
+                k, _, v = line.strip().partition(":")
+                cfg[sect][k.strip()] = v.strip()
+    except Exception:
+        pass
+    return cfg
+
+
+CFG = routing()
+
+
+def health_file():
+    """Project first: TechieFlow is installed per project, so its state lives per project too."""
+    env = os.environ.get("TF_MODEL_HEALTH_FILE")
+    if env:
+        return env
+    declared = CFG.get("cooldown_file") or ""
+    if declared:
+        return declared if os.path.isabs(declared) else os.path.join(root, declared)
+    return os.path.join(root, ".tfcore", ".session", "model-cooldown.json")
+
+
+HEALTH = health_file()
+
+
+def hkey(harness):
+    """routing.yaml writes the harness column as claude|opencode; callers may say claude-code."""
+    return "opencode" if str(harness).startswith("opencode") else "claude"
+
+
+def norm(model, harness):
+    """The key two names for the same model share.
+
+    routing.yaml writes Claude models as the aliases a person types — opus, sonnet, haiku — while
+    a transcript reports the full id it resolved to, `claude-sonnet-5`. Parking one and looking up
+    the other would silently never match, so the family word is the key on Claude. OpenCode ids
+    are already exact and are left alone."""
+    m = (model or "").strip().lower()
+    if hkey(harness) != "claude":
+        return m
+    for fam in ("opus", "sonnet", "haiku", "fable"):
+        if fam in m:
+            return fam
+    return m
+
+
+def chain_for(tier, harness):
+    k = hkey(harness)
+    out = []
+    first = (CFG["tiers"].get(tier) or {}).get(k)
+    if first:
+        out.append(first)
+    for m in (CFG["fallbacks"].get(tier) or {}).get(k, "").split(","):
+        m = m.strip()
+        if m and m not in out:
+            out.append(m)
+    return out
+
+
+# --- the cooldown file -----------------------------------------------------
+def load():
+    try:
+        with open(HEALTH, encoding="utf-8") as fh:
+            d = json.load(fh)
+        if isinstance(d, dict) and isinstance(d.get("cooldown"), list):
+            return d
+    except Exception:
+        pass
+    return {"cooldown": []}
+
+
+def save(d):
+    cut = now() - KEEP_DAYS * 86400
+    d["cooldown"] = [e for e in d["cooldown"] if int(e.get("until_epoch") or 0) > cut]
+    try:
+        os.makedirs(os.path.dirname(HEALTH), exist_ok=True)
+        tmp = HEALTH + ".tmp"
+        with open(tmp, "w", encoding="utf-8", newline="\n") as fh:
+            json.dump(d, fh, indent=1)
+        os.replace(tmp, HEALTH)
+        return True
+    except Exception as e:
+        sys.stderr.write("tf-model-pick: could not write %s (%s) — cooldown not recorded\n" % (HEALTH, e))
+        return False
+
+
+def parked(d, harness, model, at=None):
+    """The live cooldown entry for this model at time `at`, or None."""
+    at = now() if at is None else int(at)
+    k = hkey(harness)
+    want = norm(model, harness)
+    for e in d["cooldown"]:
+        if hkey(e.get("harness")) != k or norm(e.get("model"), e.get("harness")) != want:
+            continue
+        if int(e.get("since_epoch") or 0) <= at < int(e.get("until_epoch") or 0):
+            return e
+    return None
+
+
+# --- billing mode ----------------------------------------------------------
+def opencode_auth():
+    p = os.environ.get("OPENCODE_AUTH") or os.path.join(
+        os.path.expanduser("~"), ".local", "share", "opencode", "auth.json")
+    try:
+        with open(p, encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
+
+
+def opencode_catalog():
+    p = os.environ.get("OPENCODE_MODELS") or os.path.join(
+        os.path.expanduser("~"), ".cache", "opencode", "models.json")
+    try:
+        with open(p, encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
+
+
+def billing(model, harness):
+    """-> (mode, source, detail). Mode is subscription | metered | local | unknown."""
+    if hkey(harness) == "claude":
+        declared = (CFG["billing"].get("claude") or "subscription").strip()
+        if declared == "auto":
+            if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+                return ("metered", "env", "ANTHROPIC_API_KEY is set")
+            return ("subscription", "auto", "no API key in the environment")
+        if declared in ("subscription", "metered", "local"):
+            return (declared, "routing.yaml", "billing.claude")
+        return ("unknown", "routing.yaml", "billing.claude is %r" % declared)
+
+    declared = (CFG["billing"].get("opencode") or "auto").strip()
+    if declared in ("subscription", "metered", "local"):
+        return (declared, "routing.yaml", "billing.opencode")
+    provider = (model or "").split("/")[0]
+    if not provider:
+        return ("unknown", "none", "no model id")
+    # A named provider in `billing:` beats every guess below. This is the escape hatch for a
+    # local runtime called something the framework has never heard of, and for a key whose
+    # billing the owner knows and OpenCode's auth file does not say.
+    override = (CFG["billing"].get(provider) or "").strip()
+    if override in ("subscription", "plan", "metered", "local"):
+        return (override, "routing.yaml", "billing.%s" % provider)
+    if provider in PLAN_PROVIDERS:
+        return ("plan", "known-plan", "%s is a monthly plan with a per-model allowance" % provider)
+    auth = opencode_auth().get(provider)
+    if isinstance(auth, dict):
+        t = (auth.get("type") or "").lower()
+        if t == "oauth":
+            return ("subscription", "opencode-auth", "%s signed in with OAuth" % provider)
+        if t in ("api", "apikey", "api_key", "wellknown"):
+            return ("metered", "opencode-auth", "%s uses an API key" % provider)
+        return ("unknown", "opencode-auth", "%s auth type %r" % (provider, t))
+    if provider.lower().startswith(LOCAL_PROVIDERS):
+        return ("local", "provider-name", "%s runs on this machine" % provider)
+    cat = opencode_catalog().get(provider)
+    if isinstance(cat, dict):
+        # In the catalog but not signed in: it is a hosted, billable provider this machine has
+        # simply not authenticated. Saying "metered" would invent a bill; say so instead.
+        return ("unknown", "models.dev", "%s is a hosted provider with no credential here" % provider)
+    return ("unknown", "none", "provider %s is in neither auth.json nor the catalog" % provider)
+
+
+# --- the rate card ---------------------------------------------------------
+# What a model would cost at list price, per million tokens. This is a PRICE LIST, not a bill: it
+# is what makes a subscription run comparable with a metered one (owner, 2026-09-10), and it is
+# kept in its own field so that nothing ever overwrites a figure a provider actually measured.
+#
+# Two sources, project first:
+#   .tfcore/rate-card.json   {"<model id>": {"input":5,"output":25,"cache_read":0.5,"cache_write":6.25}}
+#                            for a negotiated rate, or a model the catalog has never heard of.
+#   models.dev              the catalog OpenCode already keeps at ~/.cache/opencode/models.json.
+#
+# Two simplifications, stated rather than hidden: the BASE rate is used, so a provider's
+# long-context surcharge (`context_over_200k`) is not applied — nothing records per-message
+# context length, and guessing it would be worse than the small understatement; and a rate the
+# catalog does not carry produces no number at all rather than a zero.
+def project_rate_card():
+    try:
+        with open(os.path.join(root, ".tfcore", "rate-card.json"), encoding="utf-8") as fh:
+            d = json.load(fh)
+        return d if isinstance(d, dict) else {}
+    except Exception:
+        return {}
+
+
+def rate(model, harness):
+    """-> (input, output, cache_read, cache_write, source) per 1M tokens, or None."""
+    m = (model or "").strip()
+    if not m or m.startswith("<"):        # "<synthetic>" and friends are not models
+        return None
+    own = project_rate_card()
+    for key in (m, m.split("/")[-1]):
+        r = own.get(key)
+        if isinstance(r, dict):
+            return (float(r.get("input") or 0), float(r.get("output") or 0),
+                    float(r.get("cache_read") or 0), float(r.get("cache_write") or 0),
+                    ".tfcore/rate-card.json")
+    cat = opencode_catalog()
+    provider, _, bare = m.partition("/")
+    entries = []
+    if bare and provider in cat:
+        entries = [(provider, cat[provider].get("models", {}).get(bare))]
+    else:
+        # A bare id — every Claude Code model is one, and an older OpenCode record can be. Look
+        # in anthropic first, because that is what a Claude transcript reports; then in the
+        # providers this machine is actually signed in to, because those are the ones that could
+        # have served it; then everything else alphabetically, so the same id always prices the
+        # same way. Two providers list `gpt-5.6-sol` at different rates, and picking the one you
+        # are signed in to is the difference between $4 and $5 per million input tokens.
+        signed_in = [k for k in sorted(opencode_auth()) if k in cat and k != "anthropic"]
+        rest = sorted(k for k in cat if k != "anthropic" and k not in signed_in)
+        order = (["anthropic"] if "anthropic" in cat else []) + signed_in + rest
+        entries = [(p, cat[p].get("models", {}).get(m)) for p in order]
+    for provider, entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        c = entry.get("cost")
+        if not isinstance(c, dict):
+            continue
+        return (float(c.get("input") or 0), float(c.get("output") or 0),
+                float(c.get("cache_read") or 0), float(c.get("cache_write") or 0),
+                "models.dev/" + provider)
+    return None
+
+
+# --- commands --------------------------------------------------------------
+if cmd == "pick":
+    if len(argv) < 2:
+        die("usage: tf-model-pick.sh pick <tier> [harness]")
+    tier, harness = argv[1], (argv[2] if len(argv) > 2 else "claude")
+    d = load()
+    for m in chain_for(tier, harness):
+        if not parked(d, harness, m):
+            print(m)
+            raise SystemExit(0)
+    print("inherit")   # every model in the chain is limited — the caller waits
+    raise SystemExit(0)
+
+if cmd == "chain":
+    if len(argv) < 2:
+        die("usage: tf-model-pick.sh chain <tier> [harness]")
+    tier, harness = argv[1], (argv[2] if len(argv) > 2 else "claude")
+    d = load()
+    ch = chain_for(tier, harness)
+    if not ch:
+        print("(no model declared for tier %s on %s)" % (tier, harness))
+        raise SystemExit(0)
+    for i, m in enumerate(ch):
+        e = parked(d, harness, m)
+        mark = "cooldown until %s (%s)" % (iso(e["until_epoch"]), e.get("why") or "limited") if e else "ok"
+        print("%d\t%s\t%s%s" % (i + 1, m, mark, "" if i else "   <- tier model"))
+    raise SystemExit(0)
+
+if cmd == "cooldown":
+    if len(argv) < 4:
+        die("usage: tf-model-pick.sh cooldown <harness> <model> <epoch|+minutes|probe> [\"why\"]")
+    harness, model, until = argv[1], argv[2], argv[3]
+    why = argv[4] if len(argv) > 4 else "usage limit"
+    if until == "probe":
+        until_ep = now() + PROBE_MIN * 60
+    elif until.startswith("+"):
+        until_ep = now() + int(float(until[1:])) * 60
+    else:
+        try:
+            until_ep = int(float(until))
+        except Exception:
+            die("<until> must be an epoch, +<minutes> or probe")
+    if until_ep <= now():
+        until_ep = now() + 60
+    d = load()
+    d["cooldown"] = [e for e in d["cooldown"]
+                     if not (hkey(e.get("harness")) == hkey(harness)
+                             and norm(e.get("model"), e.get("harness")) == norm(model, harness)
+                             and int(e.get("until_epoch") or 0) > now())]
+    d["cooldown"].append({"harness": hkey(harness), "model": model,
+                          "since_epoch": now(), "since": iso(now()),
+                          "until_epoch": until_ep, "until": iso(until_ep),
+                          "why": why, "app": os.path.basename(root)})
+    save(d)
+    print("cooldown: %s/%s until %s (%s)" % (hkey(harness), model, iso(until_ep), why))
+    raise SystemExit(0)
+
+if cmd == "clear":
+    d = load()
+    before = len(d["cooldown"])
+    if len(argv) == 1:
+        d["cooldown"] = []
+    else:
+        harness = argv[1]
+        model = argv[2] if len(argv) > 2 else None
+        d["cooldown"] = [e for e in d["cooldown"]
+                         if not (hkey(e.get("harness")) == hkey(harness)
+                                 and (model is None
+                                      or norm(e.get("model"), e.get("harness")) == norm(model, harness))
+                                 and int(e.get("until_epoch") or 0) > now())]
+    save(d)
+    print("cleared %d cooldown entr(y/ies)" % (before - len(d["cooldown"])))
+    raise SystemExit(0)
+
+if cmd == "billing":
+    if len(argv) < 2:
+        die("usage: tf-model-pick.sh billing <model> [harness]")
+    model = argv[1]
+    harness = argv[2] if len(argv) > 2 else ("opencode" if "/" in model else "claude")
+    print("%s\t%s\t%s" % billing(model, harness))
+    raise SystemExit(0)
+
+if cmd == "rate":
+    if len(argv) < 2:
+        die("usage: tf-model-pick.sh rate <model> [harness]")
+    model = argv[1]
+    harness = argv[2] if len(argv) > 2 else ("opencode" if "/" in model else "claude")
+    r = rate(model, harness)
+    if not r:
+        raise SystemExit(1)
+    print("%g\t%g\t%g\t%g\t%s" % r)
+    raise SystemExit(0)
+
+if cmd == "was-limited":
+    if len(argv) < 4:
+        die("usage: tf-model-pick.sh was-limited <harness> <model> <epoch>")
+    raise SystemExit(0 if parked(load(), argv[1], argv[2], argv[3]) else 1)
+
+if cmd == "status":
+    d = load()
+    live = [e for e in d["cooldown"] if int(e.get("until_epoch") or 0) > now()]
+    print("Cooldown file: %s" % HEALTH)
+    print("Routing: %s" % ("ON" if CFG["enabled"] else "OFF"))
+    print()
+    for harness in ("claude", "opencode"):
+        print("%s:" % harness)
+        for tier in ("frontier", "standard", "economy"):
+            ch = chain_for(tier, harness)
+            if not ch:
+                continue
+            use = next((m for m in ch if not parked(d, harness, m)), None)
+            mode = billing(use, harness)[0] if use else "-"
+            skipped = [m for m in ch if parked(d, harness, m)]
+            note = "  (skipping %s)" % ", ".join(skipped) if skipped else ""
+            print("  %-9s -> %-34s [%s]%s" % (tier, use or "inherit (all limited — wait)", mode, note))
+        print()
+    if live:
+        print("On cooldown now:")
+        for e in sorted(live, key=lambda x: x["until_epoch"]):
+            print("  %-9s %-34s until %s  (%s, from %s)"
+                  % (e.get("harness"), e.get("model"), e.get("until"), e.get("why"), e.get("app")))
+    else:
+        print("On cooldown now: nothing.")
+    print()
+    print("Park a model by hand:  bash .tfcore/utils/tf-model-pick.sh cooldown opencode <model> +180 \"monthly limit\"")
+    print("Unpark:                bash .tfcore/utils/tf-model-pick.sh clear opencode <model>")
+    raise SystemExit(0)
+
+die("unknown command %r — run with no arguments for the usage block" % cmd)
+PY
+rc=$?
+if [[ $rc -eq 2 ]]; then sed -n '17,32p' "$0" | sed 's/^# \{0,1\}//' >&2; fi
+exit $rc

package/.tfcore/utils/tf-opencode-audit.py

@@ -99,18 +99,34 @@ def main():
             diags.append("DIAG|dead-ref|%s" % ref)
 
     # --- project-only content ---------------------------------------------
+    # A key counts as project content only if it could actually work. Two kinds
+    # cannot, and calling them project content is what kept a repo's root config
+    # frozen with every framework agent dead (MISS-TechieFlow-20260907-08):
+    #   - the framework's own retired names: `techieflow:` and the `bmad`
+    #     prefixes it carried before the rename;
+    #   - any key whose every {file:} reference is missing from the app, so the
+    #     block cannot load whatever it names. That rule needs no list of old
+    #     prefixes and so survives the next rename.
+    dead_refs = set(d.split("|", 2)[2] for d in diags if d.startswith("DIAG|dead-ref|"))
+
+    def is_litter(key, block):
+        low = key.lower()
+        if low.startswith("techieflow:") or low.startswith("bmad:") or low.startswith("bmad-"):
+            return True
+        refs = re.findall(r"\{file:([^}]*)\}", json.dumps(block))
+        return bool(refs) and all(r in dead_refs for r in refs)
+
     project = []
     for k in app:
         if k not in tmpl:
             project.append(k)
-    for k in (app.get("agent") or {}):
-        if k not in (tmpl.get("agent") or {}):
-            project.append("agent.%s" % k)
-    for k in (app.get("command") or {}):
-        if k in (tmpl.get("command") or {}):
+    for k, blk in (app.get("agent") or {}).items():
+        if k in (tmpl.get("agent") or {}) or is_litter(k, blk):
+            continue
+        project.append("agent.%s" % k)
+    for k, blk in (app.get("command") or {}).items():
+        if k in (tmpl.get("command") or {}) or is_litter(k, blk):
             continue
-        if k.startswith("techieflow:"):
-            continue  # retired FRAMEWORK command — litter, not project content
         project.append("command.%s" % k)
 
     if app_raw == tmpl_raw:

package/.tfcore/utils/tf-perf-grade.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""tf-perf-grade.py — grade a tf-perf.sh measurement against a row's budget (see tf-perf-grade.sh).
+
+    bash .tfcore/utils/tf-perf-grade.sh --budget "p95 ttfb <= 500ms @ concurrency 50" \
+         --json tests/.artifacts/verify/perf/REQ-NFR-001.json [--json-out <file>]
+
+Prints one line: PERF-OK | PERF-MARGINAL (over the budget by up to a quarter: a warning, never a
+demotion) | PERF-FAIL (slower than budget × 1.25, or the app shed a tenth or more of the requests
+at that concurrency) | PERF-UNMEASURED with the reason (unreachable, auth wall, non-200 answers,
+errors during the run, a Debug build, fewer than 20 samples). It reads the budget, never invents
+one. Exit 0 OK or MARGINAL · 1 FAIL · 2 UNMEASURED · 3 usage.
+"""
+import json
+import os
+import re
+import sys
+
+BUDGET = re.compile(r"(p50|p95|max)\s+(ttfb|load)\s*<=\s*(\d+)\s*ms(?:\s*@\s*concurrency\s+(\d+))?", re.I)
+
+
+def grade(budget, data):
+    """-> dict(verdict, reason, metric, percentile, measured, budget, concurrency, failure_class)"""
+    m = BUDGET.search(budget or "")
+    if not m:
+        return {"verdict": "PERF-UNMEASURED", "reason": f"budget line not in the fixed form: {budget!r}"}
+    pct, metric, limit, conc = m.group(1).lower(), m.group(2).lower(), int(m.group(3)), int(m.group(4) or 1)
+    out = {"metric": metric, "percentile": pct, "budget": limit, "concurrency": conc, "measured": None, "failure_class": None}
+    st = data.get("status")
+    if st == "unreachable":
+        return dict(out, verdict="PERF-UNMEASURED", reason="the app was unreachable (a build check problem, not a speed result)")
+    if st == "redirected":
+        return dict(out, verdict="PERF-UNMEASURED", reason="auth wall: every request was redirected; present a session with --cookie or --header")
+    levels = data.get("levels") or []
+    if not levels:
+        return dict(out, verdict="PERF-UNMEASURED", reason="no measurement level in the file")
+    lvl = next((l for l in levels if l.get("concurrency") == conc), None)
+    note = ""
+    if lvl is None:
+        lvl = levels[0]
+        note = f" (measured at concurrency {lvl.get('concurrency')}, the budget names {conc})"
+    err_rate = lvl.get("error_rate") or 0
+    if err_rate >= 0.10:
+        surv = (lvl.get(f"{metric}_ms") or {}).get(pct)
+        return dict(out, verdict="PERF-FAIL", failure_class="timeout", measured=surv,
+                    reason=f"{lvl.get('errors')} of {lvl.get('samples', 0) + lvl.get('errors', 0)} requests failed at concurrency {lvl.get('concurrency')}: the budget is not servable; survivors' {pct} {metric} {surv} ms")
+    if lvl.get("non_200"):
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"non-200 answers ({', '.join(lvl['non_200'][:3])}); a wrong path or a correctness failure, not a speed result")
+    if (lvl.get("redirect_rate") or 0) > 0:
+        return dict(out, verdict="PERF-UNMEASURED", reason="some requests were redirected (auth wall); present a session and re-measure")
+    if err_rate > 0:
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"errors during the run (rate {err_rate}); re-run when quiet")
+    if str(data.get("build_config", "unknown")) != "Release":
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"build is {data.get('build_config', 'unknown')}, not Release; a Debug number is not evidence")
+    val = (lvl.get(f"{metric}_ms") or {}).get(pct)
+    if val is None:
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"no {pct} {metric} figure in the file")
+    out["measured"] = val
+    if lvl.get("weak"):
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"weak sample ({lvl.get('samples')} requests behind the {pct}); raise --requests and re-run")
+    if val <= limit:
+        return dict(out, verdict="PERF-OK", reason=f"{pct} {metric} {val} ms within {limit} ms @ concurrency {lvl.get('concurrency')}{note}")
+    if val <= limit * 1.25:
+        return dict(out, verdict="PERF-MARGINAL", reason=f"{pct} {metric} {val} ms vs budget {limit} ms @ concurrency {lvl.get('concurrency')} (marginal){note}")
+    return dict(out, verdict="PERF-FAIL", failure_class="slow-ttfb" if metric == "ttfb" else "slow-load",
+                reason=f"{pct} {metric} {val} ms vs budget {limit} ms @ concurrency {lvl.get('concurrency')}{note}")
+
+
+def main(argv):
+    budget = jpath = out = None
+    i = 1
+    while i < len(argv):
+        if argv[i] == "--budget" and i + 1 < len(argv):
+            budget = argv[i + 1]; i += 2
+        elif argv[i] == "--json" and i + 1 < len(argv):
+            jpath = argv[i + 1]; i += 2
+        elif argv[i] == "--json-out" and i + 1 < len(argv):
+            out = argv[i + 1]; i += 2
+        else:
+            print(__doc__); return 3
+    if not budget or not jpath:
+        print(__doc__); return 3
+    if not os.path.isfile(jpath):
+        print(f"PERF-UNMEASURED reason=measurement file {jpath} does not exist"); return 2
+    try:
+        data = json.load(open(jpath, encoding="utf-8"))
+    except Exception as e:
+        print(f"PERF-UNMEASURED reason=measurement file unreadable: {e}"); return 2
+    g = grade(budget, data)
+    if out:
+        os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+        json.dump(g, open(out, "w"), indent=1)
+    print(f"{g['verdict']} reason={g['reason']}")
+    return {"PERF-OK": 0, "PERF-MARGINAL": 0, "PERF-FAIL": 1}.get(g["verdict"], 2)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/.tfcore/utils/tf-perf-grade.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# tf-perf-grade.sh — grade a tf-perf.sh measurement against a row's declared budget (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-perf-grade.sh --budget "p95 ttfb <= 500ms @ concurrency 50" \
+#        --json tests/.artifacts/verify/perf/REQ-NFR-001.json [--json-out <file>]
+#
+# Prints PERF-OK, PERF-MARGINAL, PERF-FAIL or PERF-UNMEASURED with the reason. Never invents a budget.
+# Exit 0 OK or MARGINAL · 1 FAIL · 2 UNMEASURED · 3 usage. Details: tf-perf-grade.py.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "PERF-UNMEASURED reason=python3 is required"; exit 2; }
+exec python3 "$HERE/tf-perf-grade.py" "$@"