@techierathore/techieflow 1.0.3 → 1.0.4

package/.tfcore/hooks/guard-verify-deps.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — a verify run may START a dependency, never CREATE one,
+# and never point the application at a different one.
+#
+# TfLens, 2026-09-01 (MISS-TfLens-20260901-02). The configured dev database was refusing
+# connections. The agent ran `docker compose up -d db || docker compose up -d` — the
+# service is named `postgres`, so the `||` fallback executed the BARE compose command and
+# started every service, creating an application container and image the owner had to
+# delete by hand. It then exported the connection-string variable to point the whole test
+# suite at a different PostgreSQL and reported "689/689 pass" against it.
+#
+# Both halves are the same error. A verify run's entire product is trustworthy verdicts,
+# and verdicts measured against a system nobody chose are not weaker evidence — they are
+# evidence about a DIFFERENT system, reported under the checklist's name. The empty
+# substitute database then produced RENDER-EMPTY on nine controls whose real cause was
+# "no data", which is the plausible-wrong-number failure this framework exists to prevent,
+# arriving inside the verifier itself.
+#
+# §1 was already strict about unasked-for FILES (tests/.artifacts/, guard-artifacts.sh) and
+# silent about unasked-for INFRASTRUCTURE. A container, a volume and an image are exactly
+# as much machine state as a stray directory. This hook is that rule, as a rule and not a
+# paragraph (maintenance contract 3).
+#
+# REFUSES:
+#   - `docker compose up` / `docker-compose up` with no service named
+#   - any `|| docker compose up` fallback, which widens the command precisely when it failed
+#   - `docker compose run|create`, `docker run`, `docker volume create` — creating, not starting
+#   - an inline or exported connection-string variable in front of a test/run command
+# ALLOWS: `docker start <name>`, `docker compose up <service>`, `docker compose start`,
+#   `docker ps|logs|inspect`, and anything that is not one of the above.
+#
+# Wired in .claude/settings.json -> hooks.PreToolUse (matcher "Bash"); OpenCode via
+# .opencode/plugin/techieflow.js. Exit 2 + stderr = block and feed the message back.
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable — a guard that cannot
+# read its input must not stop the run.
+#
+# Tested by tests/regression/run.sh tf_013.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+TF_HOOK_INPUT="$INPUT" python3 - <<'PY'
+import json, os, re, sys
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+cmd = (data.get("tool_input") or {}).get("command")
+if not isinstance(cmd, str) or not cmd.strip():
+    sys.exit(0)
+
+def block(what, instead):
+    print("BLOCKED by TechieFlow policy: %s\n"
+          "A verify run may START a service the project already defines; it may not CREATE "
+          "one, and it may never measure the application against a different instance — a "
+          "green suite against the wrong database is worse than a red one, because it is "
+          "quotable.\n%s\n"
+          "If the dependency is down and you cannot start the project's own definition of "
+          "it BY NAME, stop and ask, naming the one command the owner should run. Record "
+          "the resolved target (host, port, database — never credentials) in the verify "
+          "report, so which system was measured is on the face of it."
+          % (what, instead), file=sys.stderr)
+    sys.exit(2)
+
+# --- creating infrastructure, rather than starting what the project already defines ------
+COMPOSE = r"docker(?:\s+compose|-compose)"
+
+# a bare `up`: no service name before the end of the segment. Flags are not service names.
+for seg in re.split(r"(?:\|\||&&|;|\||\n)", cmd):
+    seg = seg.strip()
+    m = re.search(COMPOSE + r"\s+up\b(.*)$", seg, re.I)
+    if m:
+        rest = m.group(1)
+        # drop flags and their values; whatever is left is a service name
+        words = [w for w in re.split(r"\s+", rest.strip()) if w]
+        svc = []
+        skip = False
+        for w in words:
+            if skip:
+                skip = False
+                continue
+            if w.startswith("-"):
+                if "=" not in w and w in ("--scale", "--timeout", "--project-name", "-p", "--file", "-f"):
+                    skip = True
+                continue
+            svc.append(w)
+        if not svc:
+            block("`%s` starts EVERY service in the compose file." % seg[:120],
+                  "Name the service: `docker compose up -d <service>` — and check the name, "
+                  "because a `|| docker compose up` fallback runs the bare command exactly "
+                  "when the named one was wrong.")
+
+if re.search(r"\|\|\s*" + COMPOSE + r"\s+up\b", cmd, re.I):
+    block("a `|| docker compose up` fallback widens the command when the named service failed.",
+          "Drop the fallback. If the named service does not exist, the name is wrong — fix "
+          "the name or ask; do not start everything instead.")
+
+if re.search(COMPOSE + r"\s+(?:run|create)\b", cmd, re.I) or \
+   re.search(r"\bdocker\s+(?:run|create)\b", cmd, re.I) or \
+   re.search(r"\bdocker\s+volume\s+create\b", cmd, re.I):
+    block("this CREATES container or volume state the owner did not ask for.",
+          "Start what the project defines: `docker start <name>` or `docker compose up -d <service>`.")
+
+# --- repointing the application at a different instance ----------------------------------
+# The variable is whatever the project named it, so match the SHAPE of a connection string
+# rather than a list of names that would never be complete.
+CONNSTR = r"(?:Host|Server|Data\s*Source|Endpoint)\s*=|(?:postgres|postgresql|mysql|mongodb|mssql|sqlserver|redis)(?:\+srv)?://"
+ASSIGN = r"(?:\bexport\s+|\bset\s+|^|\s|;|&&)([A-Za-z_][A-Za-z0-9_]*)\s*=\s*[\"']?([^\"'\s;&|]*)"
+
+for m in re.finditer(ASSIGN, cmd):
+    name, val = m.group(1), m.group(2)
+    if re.search(CONNSTR, val, re.I) or (re.search(r"conn|db|database|datasource", name, re.I)
+                                         and re.search(r"[=:]//|Host\s*=|Port\s*=", val, re.I)):
+        block("`%s` points the application or its tests at a connection string chosen here, "
+              "not the one the project is configured with." % name,
+              "Use the app's own configured connection. TfLens's own test helper already "
+              "carries this rule — \"there is deliberately no default here … so tests and app "
+              "can never drift onto different servers again\" — and it cost a day to learn.")
+
+sys.exit(0)
+PY
+exit $?

package/.tfcore/routing.yaml

@@ -38,6 +38,8 @@
 #      .opencode/opencode.json). Nothing changes until it runs.
 #   4. For one unattended run only, pass --model <id> to tf-goal.sh instead; the main agent uses
 #      it, the sub-agents still use the bindings from step 3.
+#   5. When a model's usage limit is reached, the tier's `fallbacks:` list is the answer — see the
+#      block below. Nothing is automatic until a limit is actually hit.
 enabled: true
 # ---------------------------------------------------------------------------
 # Tier → model id, per harness. STARTING VALUES — the owner tunes these.
@@ -54,6 +56,65 @@ tiers:
     claude: haiku
     opencode: openai/gpt-5.6-luna
 
+# ---------------------------------------------------------------------------
+# Tier → the models to try INSTEAD, in order, while the tier model is limited.
+# Comma-separated, one line per harness, same flat two-space shape as `tiers:`.
+#
+# WHAT USES IT. `bash .tfcore/utils/tf-model-pick.sh pick <tier> <harness>` returns the first
+# model in "tier model, then this list" that is NOT on cooldown. tf-goal.sh puts a model on
+# cooldown when a cycle ends in a usage limit, re-binds, and starts the next cycle on the next
+# model; tf-routing-bind.sh reads the same answer, so the sub-agents move with the main agent
+# instead of failing behind it. A cooldown expires by itself at the reset time the limit message
+# stated, and the tier goes back to its own model.
+#
+# WHEN IT DOES NOT HELP, stated plainly: on Claude Code the 5-hour and weekly limits are the
+# ACCOUNT's, not the model's, so a fallback to another Claude model is limited too. The supervisor
+# finds that out the honest way — the next cycle hits the same limit, that model goes on cooldown
+# as well, and once the chain is exhausted it sleeps until the reset exactly as it did before.
+# A per-model limit (Opus exhausted while the account is fine) is where the Claude column earns
+# its keep; a provider outage or a monthly balance is where the OpenCode column does.
+#
+# Empty list = no fallback for that tier; the supervisor sleeps. That is the safe default for
+# anyone who does not want a phase silently running on a different model.
+#
+# WHERE THE "limited until <time>" RECORD IS KEPT. In this project, at
+# .tfcore/.session/model-cooldown.json — the framework is installed per project, so its state is
+# per project too, and one project's setting never reaches another. Uncomment the line below to
+# move it: a path relative to the project root, or an absolute one. Several projects pointed at
+# one file learn about a limit from each other instead of each finding it out for themselves.
+# cooldown_file: .tfcore/.session/model-cooldown.json
+# ---------------------------------------------------------------------------
+# The OpenCode lines below are OpenCode Go models (https://opencode.ai/docs/go — a $10/month plan
+# with a per-model monthly allowance, which is exactly the limit these chains exist for). Each tier
+# falls back to a DIFFERENT model, because the allowance that ran out is per model, and then to a
+# different provider, because a whole plan can run out at once.
+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
+
+# ---------------------------------------------------------------------------
+# How each harness is PAID FOR. This is what stops one `cost_usd` column pooling
+# three different kinds of number (SCHEMA.md §2.5b).
+#   subscription  a flat fee buys a quota. Marginal dollars are zero; the unit that means
+#                 anything is tokens. Claude Max, and any OpenCode provider signed in with OAuth.
+#   metered       an API key billed per token. The dollars are real money and are summed.
+#   local         a model on this machine. No quota, no bill.
+#   auto          work it out per model — OpenCode's own auth.json says oauth or api, and a
+#                 provider it has never heard of that answers locally is local.
+# `auto` is right for OpenCode because one machine mixes all three at once. Claude Code is
+# declared, because nothing in a transcript says which plan paid for it.
+# ---------------------------------------------------------------------------
+billing:
+  claude: subscription
+  opencode: auto
+
 # ---------------------------------------------------------------------------
 # Phase → tier. One line each; values: frontier | standard | economy | inherit.
 # Rationale per row: docs/Adapter-Design.md §5.6 (the tier map is a HYPOTHESIS

package/.tfcore/tasks/_owner-language.md

@@ -0,0 +1,26 @@
+# _owner-language — how anything addressed to the owner is written
+
+Loaded by every persona. **The shape of a document lives in that document's template, never here.** These are the three rules that apply when no particular document is being written.
+
+## 1. Plain, simple English
+
+Everything the owner reads — a terminal reply, a document, a status line, the sentence on a miss — is written for a capable person who has not read one line of this framework.
+
+- **No coined terms, no shorthand.** "the framework's own script", not "the oracle". "the number you divide by", not "the denominator". If the owner would have to look a word up, it is the wrong word.
+- **Writing a glossary means the words are wrong.** Change the words. `tf-doc-check.sh` refuses a glossary section.
+- First sentence carries the answer. Name the thing, not its id. Short sentences. Never dramatise.
+
+## 2. A question for the owner goes in a file, not in the conversation
+
+When a command hits a choice only the owner can make and the answer changes what gets built: write `docs/{App}-Decision-Request.md` from `app-decision-request-tmpl.md`, render it with `tf-render-html.sh`, check it with `tf-doc-check.sh`, then say **one line** in the terminal — which file, how many decisions. Nothing else: restating it in the terminal buries the question in the context the file exists to keep clear.
+
+Never read a Decision Request back in. The owner's pasted block is the input. In YOLO, take a choice that has a clear recommendation, mark it, and continue; write the file only for one you genuinely cannot take alone.
+
+## 3. Reporting a problem upstream is never refused
+
+A gap in the framework or in a library is filed on the day you find it, whatever its size, without asking permission. The shape is in `app-library-feedback-tmpl.md`. Two things bind wherever you are:
+
+- **Every entry answers `Blocks:` first — `yes` or `no`.** That word decides whether the run stops.
+- **A non-blocking entry is filed and the work carries on.** No stopping, no asking, no page of analysis mid-run. One entry, then continue, and one line about it when the command ends.
+
+A defect goes in the feedback file. A question goes in a Decision Request. Never mixed: different readers.

package/.tfcore/tasks/_smoke-test-policy.md

@@ -12,7 +12,7 @@ A screen passes only if all three hold, at a desktop width and a mobile width:
 
 A failure on any of the three is a defect: write it into the row's Remarks (prefix `⚠ visual:` for 2 and 3) and do not report the row done. A smoke earns a row at most `Implemented`; only an executed verify run writes `Verified`.
 
-The evidence of a smoke is the file `bash .tfcore/utils/tf-verify-screens.sh --screen <name>=<route> … --base <url>` writes (`tests/.artifacts/verify/screens.json`, with a screenshot per screen and width); a row is written `Implemented` only after that run, and its Remark names the file. The application is booted with `bash .tfcore/utils/tf-verify-boot.sh start`, which also drives a Blazor Hybrid Windows head; a head the script cannot boot leaves the row below `Implemented` with the reason.
+The evidence of a smoke is the file `bash .tfcore/utils/tf-verify-screens.sh --screen <name>=<route> … --base <url>` writes (`tests/.artifacts/verify/screens.json`, with a screenshot per screen and width); a row is written `Implemented` only after that run, and its Remark names the file. The application is booted with `bash .tfcore/utils/tf-verify-boot.sh start`, which also drives an embedded-browser desktop head Windows head; a head the script cannot boot leaves the row below `Implemented` with the reason.
 
 ## Run it yourself
 

package/.tfcore/tasks/amend-docs.md

@@ -14,13 +14,14 @@ First: `bash .tfcore/utils/tf-phase.sh start amend-docs {App}` prints the start
 
 1. Read the BRD and note the highest `BRD-N`. On a Large project the BRD and checklist are the phase's: `appPhase` in `core-config.yaml` names it, phase 1 is `docs/{App}-BRD.md`, phase n is `docs/{App}-Pn-BRD.md`; the highest id is the highest across every phase. No BRD means no amendment: stop and point at day-1. Note whether the checklist exists.
 2. Sort every point of the change into ADD (a new capability, actor, screen or integration), MODIFY (an existing item whose behaviour changed, mapped to its `BRD-N`), REMOVE (scope dropped, mapped to its `BRD-N`) or ARCH (a new module, flow, package or decision).
-3. Show the change-set as a numbered table (ADD with the next ids, MODIFY as old to new, REMOVE with the reason, ARCH by decision) and wait for "go" or corrections. This is the only question. In YOLO mode apply it without waiting.
+3. Show the change-set as a numbered table (ADD with the next ids, MODIFY as old to new, REMOVE with the reason, ARCH by decision) and wait for "go" or corrections. **A table, not an essay: no glossary, no verification chapter, no re-argued history.** This is the only question. In YOLO mode apply it without waiting. If a point of the change turns on something only the owner can decide, do not argue it here — write `docs/{App}-Decision-Request.md` per `.tfcore/tasks/_owner-language.md`, render it, and say one line naming the file and how many decisions it holds.
 4. BRD. ADD: append a ledger item with the next id, its screen, its mockup link and its acceptance line "When <actor> <does what> on <screen>, then <observable result>"; a new screen gets a row in the Screens and flow table and a Planned row in the Development status table. MODIFY: edit the item in place, same id. REMOVE: `~~BRD-N~~ (removed {date}: reason)`, never deleted. If the additions would take a Small project past 50 requirements, raise it to Medium: `bash .tfcore/utils/tf-day1-files.sh {App} --size M` and the Size in every document header. If they would take a Medium project, or one phase, past 100 requirements or 20 screens, stop and propose a phase split: a new row in `docs/{App}-Phases.md` (written with `--size L` when absent) and a new `docs/{App}-Pn-BRD.md`, instead of growing this one.
 5. Architecture, when in scope and ARCH items exist: edit the affected sections in place, and add a Decisions log row (date, decision, why, status `planned` naming the BRD item) for every new decision or package. A reversed decision gets a new row; the old row stays.
 6. Mockups: when a screen was added or changed, run `.tfcore/tasks/mockups.md` with `--update`, so every screen in the BRD has a current mockup before the checklist changes.
 7. Checklist, only if it exists. ADD: `bash .tfcore/utils/tf-split-brd.sh {App} --add-missing` appends rows for the new items; correct their class. MODIFY: set the rows derived from that item to `Needs re-verify` with a Remark saying what changed. REMOVE: set them to `N/A (removed {date})` and keep the rows. Where the mapping from an item to its rows is unclear, ask, do not guess. If the checklist does not exist yet, the next day-1 stage 2 picks everything up.
 8. If the amendment changed code-level flows, say that `*devguide {App} --update` is due after the next build.
-9. Decide whether this amendment is a miss: should the original documents plainly have said this (a behaviour that was always required, or two sections that contradicted each other)? Then run `*log-miss {App} "<one sentence>"`. A change of mind or a feature decided today is scope arriving late, not a miss.
-10. `bash .tfcore/utils/tf-doc-check.sh --app {App}`; fix every FAIL.
-11. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"amend-docs"`.
-12. Report: items added (ids), modified, removed, the highest id now, what changed in the Architecture, the checklist rows touched, and the next command from the gate.
+9. Close what this amendment fixed: `bash .tfcore/utils/tf-emit.sh --open-misses {App} --artifact-class doc` lists the open misses whose deficient artifact is a document. Close the ones this amendment resolves in one call: `bash .tfcore/utils/tf-fix-close.sh {App} --misses <id>,<id> --fix-cmd amend-docs --verdict Verified`. Where the mapping from a miss to this amendment is unclear, ask, do not guess. Without this a document miss can never close: `*fix-issues` and `*build-phase` close off checklist rows the verifier touched, which a BRD edit never is.
+10. Decide whether this amendment is a miss: should the original documents plainly have said this (a behaviour that was always required, or two sections that contradicted each other)? Then run `*log-miss {App} "<one sentence>"`. A change of mind or a feature decided today is scope arriving late, not a miss.
+11. `bash .tfcore/utils/tf-doc-check.sh --app {App}`; fix every FAIL.
+12. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"amend-docs"`.
+13. Report: items added (ids), modified, removed, the highest id now, what changed in the Architecture, the checklist rows touched, and the next command from the gate.

package/.tfcore/tasks/build-phase.md

@@ -10,7 +10,7 @@ First: `bash .tfcore/utils/tf-phase.sh start build-phase {App}` prints the start
 
 ## Steps
 
-1. `bash .tfcore/utils/tf-build-list.sh {App} --prompts` prints the mode, the working list, the clusters and one sub-agent prompt per cluster. FIX means the verifier or a smoke failed rows: build only those. FRESH means every open row. NOTHING means run the status gate and stop. A row without an acceptance line is refused: fix the checklist first, then re-run.
+1. `bash .tfcore/utils/tf-build-list.sh {App} --prompts` prints the mode, the working list, the clusters and one sub-agent prompt per cluster. The working list is **every** open row in both FIX and FRESH; FIX only means the rows the verifier or a smoke failed come first. NOTHING means run the status gate and stop. A row without an acceptance line is refused: fix the checklist first, then re-run.
 2. Spawn every cluster in one turn, each with its printed prompt unchanged: `[trblazeui]` clusters through `/trblazeui`, `[techierag]` through `/techierag`, `[builder]` through the harness's builder sub-agent (`tf-builder` when registered, else the general one). Wait for all of them. A cluster that returns `PARTIAL` is re-spawned with its missing rows. Context pressure is a reason to delegate more, never to stop, and a working list is never shortened: "run build-phase again for the rest" is not an ending.
 3. A row that cannot be built as written (no mockup, two rows that contradict, a behaviour the BRD plainly needed and never named): take the sensible reading, write it in the row's Remarks, keep building, and log the gap as a `miss` (`.tfcore/tasks/_metrics-emit-gate.md`) with `miss_class` `unspecified-gap` or `spec-contradiction`, `artifact` naming the document, `found_by` `agent-review`, `found_phase` `build-phase`. A library gap goes into `docs/{App}-<Library>-Feedback.md` (from `.tfcore/templates/v4custom/app-library-feedback-tmpl.md`, one file per library) and the row becomes `Blocked`; never a workaround.
 4. `bash .tfcore/utils/tf-build.sh`: PASS, or FAIL with the real errors (fix them, fanning out by file when there are many), or NOT-RUN naming the rungs tried, which is a host problem and never a blocker. `bash .tfcore/utils/tf-build.sh test` runs the tests.

package/.tfcore/tasks/create-deep-research-prompt.md

@@ -276,3 +276,7 @@ CRITICAL: collaborate with the user to develop specific, actionable research que
 - Balance comprehensiveness with focus
 - Document assumptions and limitations clearly
 - Plan for iterative refinement based on initial findings
+
+## Record the run
+
+First action of this task: `bash .tfcore/utils/tf-phase.sh start create-deep-research-prompt {App}`. Last action: one `runs.jsonl` record carrying `"cmd":"create-deep-research-prompt"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows. No status gate here — this command advances no phase. Telemetry has no veto: if the write fails, the command still succeeded.

package/.tfcore/tasks/create-doc.md

@@ -99,3 +99,7 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 - Select options 2-9 from data/elicitation-methods only
 - Provide detailed rationale explaining decisions
 - End with "Select 1-9 or just type your question/feedback:"
+
+## Record the run
+
+First action of this task: `bash .tfcore/utils/tf-phase.sh start create-doc {App}`. Last action: one `runs.jsonl` record carrying `"cmd":"create-doc"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows. No status gate here — this command advances no phase. Telemetry has no veto: if the write fails, the command still succeeded.

package/.tfcore/tasks/create-project-brief.md

@@ -0,0 +1,22 @@
+# create-project-brief
+
+`*create-project-brief {App}` writes `docs/{App}-Brief.md`, the one page day-1 reads. It is the cheapest place to be wrong, so it is short and the owner corrects it in two minutes.
+
+First: `bash .tfcore/utils/tf-phase.sh start create-project-brief {App}` prints the start time and marks the command running.
+
+## Inputs
+
+- `{App}`, or read it from `core-config.yaml`.
+- Whatever the owner gives: a paragraph, a brainstorm result (`docs/brainstorming-session-results.md`), a conversation, or nothing.
+
+## Steps
+
+1. Read `.tfcore/templates/v4custom/app-brief-tmpl.md` — its schema block is the required shape.
+2. Fill the five sections from what the owner gave. Ask only for what you cannot infer, one round of questions, all at once. In YOLO mode take the sensible reading and mark it.
+3. **A thing you do not know goes in "Open questions", never into a section as a guess.** Day-1 then asks rather than assumes, which is the whole point of writing this before the Architecture exists.
+4. Every "Must do" line is an outcome a user gets, numbered, one per line. A line needing a paragraph is two lines.
+5. Write `docs/{App}-Brief.md`. Never a `-v2`; an amended brief is edited in place.
+6. `bash .tfcore/utils/tf-doc-check.sh docs/{App}-Brief.md`; fix every FAIL.
+7. Render it: `bash .tfcore/utils/tf-render-html.sh docs/{App}-Brief.md`. The owner reads the HTML.
+8. Close: one `runs.jsonl` record carrying `"cmd":"create-project-brief"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows. No status gate — the project has no checklist yet.
+9. Report in one line: the file, and how many open questions it carries. Then say the next command is `*day1-greenfield {App}` or `*day1-brownfield {App}`.

package/.tfcore/tasks/day1-brownfield.md

@@ -8,7 +8,7 @@ First, before anything else: `bash .tfcore/utils/tf-phase.sh start day1-brownfie
 
 1. `{App}` if missing. PascalCase, no spaces; reject anything else and ask again.
 2. Hints, once: list the markdown files found under `docs/` and at the root (excluding `docs/OldDocs/`, `CLAUDE.md`, `PROJECT-STATUS.md`, and `README.md` unless it holds requirements), then ask: "Reply `all` (or press enter) to harvest all of them, or list the ones to use. Add extra paths or drafting instructions in the same reply. `none` harvests nothing." Parse once: file names into the harvest list, anything else into drafting instructions. Never ask merge-or-new.
-3. The stack: "Which answer set: `dotnet` (`.tfcore/templates/stack-defaults/dotnet.md`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then only the questions the set leaves open, and only where the code does not already answer them.
+3. The stack: "Which answer set (the files under `.tfcore/templates/stack-defaults/`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then only the questions the set leaves open, and only where the code does not already answer them.
 4. The size: count the routed pages in the code (every route counts, sign-in included; dialogs and tabs are regions of a page) and the roles, then confirm: "Size: Small (up to 10 screens, one role, 50 requirements), Medium (up to 20 screens, 100 requirements) or Large (split into phases)? I count {N} screens and {N} roles, so I propose {X}." Kind is `app`, or `library` for a component or service library.
 
 ## Steps, in this order
@@ -21,7 +21,7 @@ First, before anything else: `bash .tfcore/utils/tf-phase.sh start day1-brownfie
 6. BRD, second half: the Requirements ledger, one `BRD-N` per thing the verifier will test, each naming its screen, linking its mockup and carrying one acceptance line "When <actor> <does what> on <screen>, then <observable result>". Harvested documents come first: every "the system shall" or "the user can" line becomes an item, attributed, and every table, screen inventory and workflow they hold carries in, never compressed to a one-liner. Then the code: what it already does becomes items too. Mark inferred items `<!-- inferred — please verify -->`. The Non-functional table takes a `perf-budget:` only where the owner stated a number, and the logging requirement from the answer set, recorded as met when the scan found it wired. The Development status table has one row per screen with Verified and Open counts from the strongest evidence. If the count would pass the size cap, propose a phase split instead of merging items.
    Large: steps 4 to 6 run once per phase of the Phases table, phase 1 in `docs/{App}-BRD.md` and `docs/{App}-UIDesign.md`, phase n in `docs/{App}-Pn-BRD.md` and `docs/{App}-Pn-UIDesign.md`, each header carrying `Phase | n of m` and its own Size, ids running on across phases.
 7. Checklist: run `.tfcore/tasks/split-brd.md` for `{App}` (Large: with `--all-phases`, one checklist per phase). If a phased plan is among the harvested documents, split-brd migrates its statuses; the plan then moves to `docs/OldDocs/`.
-8. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open. For dotnet the instance-field prefix follows the drift scan of step 3: the dominant style if one reaches 80 percent, else `obj`; a drafting instruction overrides. "Project rules" holds only rules true of this project alone.
+8. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open. Where the stack file leaves a naming convention open, it follows the drift scan of step 3: the dominant style if one reaches 80 percent, else the stack file's default; a drafting instruction overrides. "Project rules" holds only rules true of this project alone.
 9. `bash .tfcore/utils/tf-day1-files.sh {App} --prefix {obj|none}` writes `.editorconfig`, `AGENTS.md` and `CLAUDE.md`.
 10. `bash .tfcore/utils/tf-gitignore-audit.sh . --fix`. Read its output. Any untracking commands it prints go into your summary for the owner to run; agents never run git.
 11. Build once through `.tfcore/templates/v4custom/build-invocation-ladder.md`. A real compile error becomes one line under Known blockers; a wrong-rung error never does.

package/.tfcore/tasks/day1-greenfield.md

@@ -11,7 +11,7 @@ Ask once each, and nothing per section:
 1. `{App}` if missing. PascalCase, no spaces.
 2. The concept: "Describe the app, any length: a sentence, paragraphs, bullets, half-baked notes, comparisons to other apps. You will edit the document afterwards." Read all of it. Never cap or summarise the owner's input.
 3. Hints, optional: paths to notes or mockups to harvest, and drafting instructions. `none` is fine.
-4. The stack: "Which answer set: `dotnet` (`.tfcore/templates/stack-defaults/dotnet.md`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then ask only the questions the set leaves open (for dotnet: Q4, and the rendering mode of Q8).
+4. The stack: "Which answer set (the files under `.tfcore/templates/stack-defaults/`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then ask only the questions that answer set leaves open — each set names its own.
 5. The size: count the routed pages in the concept (every page with its own route, sign-in included; dialogs and tabs are regions of a page) and the roles, then ask: "Size: Small (up to 10 screens, one role, 50 requirements), Medium (up to 20 screens, 100 requirements) or Large (split into phases)? I count {N} screens and {N} roles, so I propose {X}." Kind is `app` unless the concept is a library.
 
 Then, in this order:
@@ -32,7 +32,7 @@ Only with `--stage2`, and only when `docs/{App}-BRD.md` exists. Ask nothing.
 
 0. If the owner gave corrections at the review, apply them to the stage-1 documents first (ids never renumbered; `bash .tfcore/utils/tf-doc-check.sh --app {App}` must pass), count them, and after this run's record append a `review` record: `{"kind":"review","phase":"day1-review","reviewed_run_id":"<stage 1 started>","correction_run_id":"<this run's started>","corrections":N,"what":"<one sentence>"}` through `tf-emit.sh misses`.
 1. Checklist: run `.tfcore/tasks/split-brd.md` for `{App}` (Large: with `--all-phases`, one checklist per phase). The owner never types `*split-brd`.
-2. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open (for dotnet, the instance-field prefix, default `obj`). "Project rules" stays empty unless the concept demands a rule true of this project alone.
+2. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open, taking that file's stated default for each. "Project rules" stays empty unless the concept demands a rule true of this project alone.
 3. `bash .tfcore/utils/tf-day1-files.sh {App} --prefix {obj|none}` writes `.editorconfig`, `AGENTS.md` and `CLAUDE.md` from their templates.
 4. UsageGuide: `docs/{App}-UsageGuide.md` from `app-usageguide-tmpl.md`. The Test users table lists the intended accounts, one per role, none created. The Execution guide is at roadmap level, marking commands that depend on projects not yet built. One "How to test" section per screen in navigation order, naming the user, the steps, the expected result and the REQ ids.
 5. `bash .tfcore/utils/tf-gitignore-audit.sh . --fix`. Read its output. Any untracking commands it prints go into your summary for the owner to run; agents never run git.

package/.tfcore/tasks/facilitate-brainstorming-session.md

@@ -134,3 +134,7 @@ Generate structured document with these sections:
 - Always ask before switching techniques: "Ready to try a different approach?"
 - Offer options: "Should we explore this idea deeper or generate more alternatives?"
 - Respect their process and timing
+
+## Record the run
+
+First action of this task: `bash .tfcore/utils/tf-phase.sh start facilitate-brainstorming-session {App}`. Last action: one `runs.jsonl` record carrying `"cmd":"facilitate-brainstorming-session"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows. No status gate here — this command advances no phase. Telemetry has no veto: if the write fails, the command still succeeded.

package/.tfcore/tasks/generate-html.md

@@ -2,7 +2,7 @@
 
 Convert one or more **human-readable** markdown files to self-contained HTML using the shared shell. Use this when you need to render documents that `*render-workflow-docs` does not cover (the UsageGuide, the DevGuide, library-feedback docs, ad-hoc design notes, legacy/archived docs). Note: suffixed doc variants like `-v2` are banned by the collision policy (day1-brownfield §1.6) — superseded docs live unmodified in `docs/OldDocs/`.
 
-**NEVER render the checklist to HTML.** The `*-Checklist.md` (and its Requirements Status table) is an **AI-agent working document** — agents read it in markdown. An HTML mirror just burns tokens and drifts from the source. If asked to render a `*-Checklist.md`, decline and explain it's an agent doc; if a stale `*-Checklist.html` exists from before this rule, the user may delete it.
+**NEVER render an agent working document to HTML.** Two are banned by name and `tf-render-html.sh` refuses both with exit 2: the **requirements checklist** `*-Checklist.md` (and its Requirements Status table), and the **miss log** `*-Misses.md`. Agents read them in markdown; an HTML mirror burns tokens and drifts from the source. If asked to render either, decline and explain it is an agent document; if a stale `*-Checklist.html` or `*-Misses.html` exists from before this rule, delete it. The test for any other file: **if the only reader is an agent, it stays markdown.**
 
 ## Why this exists
 
@@ -113,3 +113,7 @@ Print one line per rendered file: the absolute output path. End with: `Open each
 - [ ] Mermaid validity pass done (shell §5.5): every non-trivial label double-quoted, no `end` node ids, bare labels fixed not emitted
 - [ ] No agent-facing authoring note (Depth/Mermaid mandate, template how-to) rendered as visible text — leaked ones omitted and reported
 - [ ] Copy buttons present on every `<pre>` (added by JS, no need to inject manually)
+
+## Record the run
+
+First action of this task: `bash .tfcore/utils/tf-phase.sh start generate-html {App}`. Last action: one `runs.jsonl` record carrying `"cmd":"generate-html"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows. No status gate here — this command advances no phase. Telemetry has no veto: if the write fails, the command still succeeded.

package/.tfcore/tasks/handoff-phase.md

@@ -23,26 +23,28 @@ The Usage Guide was created at day-1 (`day1-*` §7.4) from `.tfcore/templates/v4
 
 Below, "populate" means refresh these sections of the existing doc. Hard rules:
 
-- **No narrative prose anywhere.** No "this app uses Blazor Server because…", no caveats, no explanations. The deployment-steps section must look like a runbook — one command per line, numbered in execution order.
+- **No narrative prose anywhere.** No "this app is built this way because…", no caveats, no explanations. The deployment-steps section must look like a runbook — one command per line, numbered in execution order.
 - **Skip any step that doesn't apply.** If the repo has no SQL migrations, omit the database-setup step entirely — do not leave "N/A" placeholders or "// not applicable" comments.
 - **No optional steps in the numbered list.** The numbered deployment-steps section is the minimum sufficient set of commands to go from `git clone` to a running app. Anything optional goes in "Known limitations" or a separate doc.
 
 Detection sources for each section:
 
-- **Prerequisites**: SDK version from `global.json` / `.csproj` `<TargetFramework>`. Add a one-line entry for each external runtime the build/test commands depend on (Node only if Playwright tests exist; Postgres/SQL Server/etc. only if migrations exist; MAUI workload only if there's a MAUI project). One line each. No prose.
+**Every command below comes from the project, never from this file.** The restore, build, run and test commands are the ones the project's Architecture stack table and `docs/{App}-Coding-Standards.md` name, and `bash .tfcore/utils/tf-build.sh --print` prints the build command this repository actually uses. A toolchain assumed here would be wrong on the next project.
+
+- **Prerequisites**: the runtime version from wherever this stack pins it (the Architecture stack table names the file). Then one line for each external runtime the build, run or test commands depend on — a package runtime only if the tests need one, a database server only if migrations exist, a platform workload only if a project targets that platform. One line each. No prose.
 - **Deployment steps**: detect in this order and emit one numbered step per command:
   1. `git clone <repo>` (always)
-  2. `dotnet restore` (always)
-  3. SQL migrations — scan `database/`, `db/migrations/`, `src/*Db/Scripts/`, and any DbUp project's `<EmbeddedResource>` paths. List `.sql` files in lexicographic order, one per line. If a DbUp project exists, prefer `dotnet run --project src/{AppName}.Db` as a single step instead of listing each SQL file.
-  4. `dotnet build`
-  5. Backend run — find the API/service startup project. One `dotnet run --project ... --urls http://localhost:5100` line.
-  6. Frontend run — find the Web/UI startup project. One `dotnet run --project ... --urls http://localhost:5099` line.
-  7. "Open http://localhost:5099 in a browser."
-  - For MAUI: replace step 5/6 with `winrun "dotnet build src/{AppName}.Maui"` then `winrun "dotnet run --project src/{AppName}.Maui"`.
-  - If frontend and backend are the same project (Blazor Server-only): collapse steps 5+6 into one.
-- **Test**: `dotnet test`. Add `npx playwright test` ONLY if the repo has Playwright tests checked in.
+  2. Restore dependencies — the stack's restore command (always)
+  3. Database migrations — scan the migration folders the Architecture names, plus the conventional ones (`database/`, `db/migrations/`, `migrations/`). List the migration files in the order they run, one per line; if the stack has a migration runner, prefer one step invoking it over listing every file.
+  4. Build — the stack's build command
+  5. Backend run — find the service or API entry point. One line, with the port it listens on.
+  6. Frontend run — find the UI entry point. One line, with its port.
+  7. "Open http://localhost:<frontend port> in a browser."
+  - A packaged desktop or mobile head replaces steps 5 and 6 with that platform's build-and-run pair.
+  - If frontend and backend are one process, collapse steps 5 and 6 into one.
+- **Test**: the stack's test command. Add the browser-test command ONLY if such tests are checked in.
 - **Smoke checklist**: one checkbox per top-level BRD capability (5–10 max). Each line is a user action, not a technical step ("Log in as admin and load the dashboard" — NOT "verify JWT validation").
-- **Known limitations**: pull every `Blocked` REQ row from the checklist Status table + every entry from the per-library feedback files (`docs/{AppName}-TrBlazeUI-Feedback.md`, `docs/{AppName}-TechieRag-Feedback.md`). One line each. Cross-reference to issue IDs (TR-NNN, TR-RAG-NNN).
+- **Known limitations**: pull every `Blocked` REQ row from the checklist Status table + every entry from the per-library feedback files (`docs/{AppName}-{Library}-Feedback.md`, one per library the project uses). One line each. Cross-reference each to its issue id.
 
 **If you find yourself writing more than one line per numbered step, you're doing it wrong** — the user has explicitly called out that the deployment steps got polluted with "unnecessary details" in past runs. Strip aggressively.
 
@@ -50,7 +52,7 @@ Detection sources for each section:
 
 - `current_phase: Handoff` (the user manually sets `Released` after UAT passes — §5)
 - `last_updated`: today
-- `last_verified_build: PASS` (you just verified — confirm with `dotnet build` if uncertain)
+- `last_verified_build: PASS` (you just verified — confirm with `bash .tfcore/utils/tf-build.sh` if uncertain)
 - `last_verified_date`: today
 - "Where I am": one paragraph — "All REQ-* verified; awaiting UAT per usage doc."
 - "Next command to run": `Manual UAT per docs/{AppName}-UsageGuide.md smoke checklist.`
@@ -90,7 +92,7 @@ Run `.tfcore/tasks/devguide.md` for `{AppName}` (`*devguide {AppName}`) so the s
 
 ### 4. Consolidate the per-library feedback files
 
-For EACH of `docs/{AppName}-TrBlazeUI-Feedback.md` and `docs/{AppName}-TechieRag-Feedback.md` (and any other `docs/{AppName}-{LibName}-Feedback.md`) that exists — they are separate files because each goes to a different team:
+For EACH `docs/{AppName}-{Upstream}-Feedback.md` that exists — one per library the project uses, plus the framework's own — they are separate files because each goes to a different team:
 - Deduplicate entries (same expected/actual pair = duplicate; merge them).
 - Sort by severity: blocker → major → minor → nice-to-have.
 - Ensure each entry has all the schema fields (Severity, Repro, Expected, Actual, Encountered in, Workaround, Suggested fix). Fill in missing ones from context if possible.
@@ -108,11 +110,11 @@ If no feedback file exists (no library issues encountered), skip this step.
 
 Deliver:
 - "✔ {AppName} is ready for UAT." OR
-- "⚠ {AppName} has {N} `Blocked` (library-gap) items — see docs/{AppName}-TrBlazeUI-Feedback.md / docs/{AppName}-TechieRag-Feedback.md before UAT."
+- "⚠ {AppName} has {N} `Blocked` (library-gap) items — see the `docs/{AppName}-{Upstream}-Feedback.md` files before UAT."
 
 Then explicitly tell the user:
 1. Open `docs/{AppName}-UsageGuide.md` and run the smoke checklist.
-2. Hand each per-library feedback file to its team (or file as GitHub issues against that library's repo): `docs/{AppName}-TrBlazeUI-Feedback.md` → TrBlazeUI team, `docs/{AppName}-TechieRag-Feedback.md` → TechieRag team. The library teams use this same framework, so the file drops straight into their flow.
+2. Hand each feedback file to the team named in its file name (or file its entries as issues against that repository). Those teams use this same framework, so the file drops straight into their flow.
 3. After UAT passes, manually update `PROJECT-STATUS.md`: `current_phase: Released`.
 4. For end-user / external documentation, run `*productguide {AppName}` (flow-master) — it builds a screenshot-illustrated, task-oriented user manual (MD + HTML) from the DevGuide's screen map + captured screenshots. On-demand; re-run with `--update` as the UI evolves.
 

package/.tfcore/tasks/metrics-report.md

@@ -108,6 +108,8 @@ Written: docs/metrics/METRICS.md + .html
 {if backfilled records present: "Backfilled data is reported in a separate column and cannot support a published first-pass rate."}
 ```
 
+Then one `runs.jsonl` record carrying `"cmd":"metrics-report"`, written as `.tfcore/tasks/_metrics-emit-gate.md` shows; `bash .tfcore/utils/tf-phase.sh start metrics-report {App}` is the first action of this task, so the start time is measured.
+
 Then stop. Do not run the status gate — this task reports on history, it does not advance the project, and PROJECT-STATUS is not where metrics go.
 
 ## Hard rules

package/.tfcore/tasks/verify-phase.md

@@ -28,7 +28,7 @@ The phase's checklist, UIDesign and `docs/mockups/` (`appPhase` in `core-config.
 
 1. `bash .tfcore/utils/tf-verify-list.sh {App} {scope}` prints the rows to grade with their acceptance line, screen, route, mockup and perf budget, the screens to drive, and the test users; it writes `tests/.artifacts/verify/list.json`. Every row in scope is graded whatever its status; only N/A is skipped, so a `Verified` row is re-confirmed and an old `Done` claim is tested. NOTHING means run the status gate and stop. A row without an acceptance line cannot be graded: fix the checklist first. A dialog is listed under its parent screen and checked there; never give a dialog a route so it can be tested.
 2. `bash .tfcore/utils/tf-verify-env.sh` prints READY, or the one command the owner must run once.
-3. `bash .tfcore/utils/tf-verify-boot.sh start` boots the head it finds (`--head` or `--project` when there are several) and prints BOOTED with a URL, or a CDP URL for a Blazor Hybrid Windows head, which the browser tools attach to. A dependent service (database, API) is yours to start first, from its own configuration, in order. NONE `kind=build-error`: every row fails the build check; go to step 6. NONE `kind=host` or `kind=no-driver` (an Android, iOS or Mac head): go to step 6 as well; those rows are written "not verified" with the reason. Never a static-only pass, never "the owner should start it".
+3. `bash .tfcore/utils/tf-verify-boot.sh start` boots the head it finds (`--head` or `--project` when there are several) and prints BOOTED with a URL, or a CDP URL for an embedded-browser desktop head, which the browser tools attach to. A dependent service (database, API) is yours to start first, from its own configuration, in order. NONE `kind=build-error`: every row fails the build check; go to step 6. NONE `kind=host` or `kind=no-driver` (an Android, iOS or Mac head): go to step 6 as well; those rows are written "not verified" with the reason. Never a static-only pass, never "the owner should start it".
 4. Tests. Every UI and functional row has one test whose title starts with its id, written from the acceptance line, black box, under `tests/verify/`; an NFR row without a screen has a unit test carrying its id in the test project, or is not observable. Reuse a test that exists. Fan out one test-writer sub-agent per screen group in one turn, each with its rows, their acceptance lines, the URL and the test user; a test writer touches no source. Sign in as a UsageGuide test user (`.tfcore/tasks/_smoke-test-policy.md`).
 5. Run the checks, with `<url>` from step 3 and, on a signed-in app, the session cookie from the test login for the tools that take `--cookie`:
    - `bash .tfcore/utils/tf-verify-tests.sh --base <url>`

package/.tfcore/telemetry/SCHEMA.md

@@ -127,6 +127,34 @@ So `tf-emit.sh` detects it and injects it. **Never write `harness` into an emit
 
 Provenance rule applied once more: **never pool `cost_usd` across harness** — Claude records are `null`, and a sum over mixed records silently under-reports. Tokens may be compared across harness; dollars may not.
 
+### 2.5b How the model was paid for (added 2026-09-10; injected by `tf-emit.sh`, never emitted by an agent)
+
+`cost_usd` alone answers *how much* and never *of what*, and on one machine it is three different quantities at once. The owner found this on 2026-09-10 (MISS-TechieFlow-20260910-02): a `runs.jsonl` here holds OpenCode records on a metered API key where the dollars are real money, OpenCode records on an OAuth subscription where OpenCode records **0.0** because the plan was already paid for, OpenCode records on a model running on this machine where there is no bill at all, and Claude Code records that are permanently `null`. Summing them produces a number that is neither the money spent nor the effort used, and the two zeroes are indistinguishable from a free run.
+
+| Field | Type | Meaning / source |
+|---|---|---|
+| `billing_mode` | string | `subscription` \| `metered` \| `local` \| `mixed` \| `unknown`. Resolved per observed model by `bash .tfcore/utils/tf-model-pick.sh billing <model> <harness>`: OpenCode's own `auth.json` says `oauth` (a plan) or `api` (a key), a provider that runs on this machine is `local`, a provider with no credential is `unknown` and is never assumed to be billable, and `routing.yaml` `billing:` overrides any of it by name. Claude Code is **declared** in `billing.claude` (default `subscription`), because nothing in a transcript says which plan paid for it. `mixed` when one window ran models of more than one mode — which is exactly what a fallback from a subscription to a metered key looks like. |
+| `cost_source` | string | `opencode-db` where a per-message cost was read, `none` where there is no cost source at all. **Never a rate card.** |
+
+`billing_mode` has five values, and the `plan` one is the reason the field is not a boolean:
+
+| Value | What the provider's cost number is |
+|---|---|
+| `subscription` | Nothing, or a recorded `0.0`. A flat fee bought the quota before the run started. |
+| `plan` | **Allowance consumed against a per-model limit, not an invoice.** OpenCode Go is $10/month with a $15–$60 monthly allowance *per model* and 5-hour / weekly / monthly thresholds (<https://opencode.ai/docs/go>), so its dollars are a meter — and they are precisely the numbers that produce the limit `routing.yaml` `fallbacks:` exists for. Detected from the provider name, because an API key alone cannot tell a plan from a per-token bill. |
+| `metered` | Money actually billed, per token. |
+| `local` | No bill at all. |
+| `mixed` / `unknown` | Several modes in one window; or nothing here could tell. `unknown` is never quietly treated as billable. |
+
+**Money is never computed into a record.** Tokens are what the framework measures and stores — per model, main thread and sub-agents apart (§2.5, §2.6) — and turning them into a price is a *reporting* job, done by `tf-metrics.sh` (and by any other reader, TfLens included) from the fields already on the stream. That is §8's existing rule, *derived metrics are computed, never stored*, applied to money; it is why a rate card can change, or a reader disagree with this one, without a single record becoming wrong, and why every run ever recorded is re-priced the moment the rate card is corrected. The shared rate lookup is `bash .tfcore/utils/tf-model-pick.sh rate <model>`, which reads the models.dev catalog and lets a project's own `.tfcore/rate-card.json` win.
+
+Two simplifications in that price, stated rather than hidden: the **base** rate is used, so a provider's long-context surcharge is not applied (nothing records per-message context length, and guessing it would be worse than the small understatement); and a model the rate card does not carry produces no number rather than a zero.
+| `fallback_from` | string | **`runs`/`gates` only.** The tier's own model, named here when the run started while that model was on cooldown for a usage limit. It is what separates *"routing drifted"* from *"the tier model was out of quota and the chain moved on"* — both of which set `routed:false`, and only one of which is a problem. |
+
+**The reporting rule, enforced in `tf-metrics.sh` and not merely stated here:** the report carries **three** money lines and never merges them — *list price*, computed over every record that can be priced and labelled a price rather than a bill; *plan allowance used*, per model, over `billing_mode:"plan"` records, because that is the meter a per-model limit is read against; and *money billed*, over `billing_mode:"metered"` records only. Each prints what it excluded. A window whose models were paid for in different ways contributes real money that cannot be separated from the part a subscription had already covered, so it gets its own line rather than being folded into any of the three. Per-model spend is attributed only where the window ran a single model; splitting one window's dollars across several models by token share is arithmetic, not measurement — the same line §5.5.3 draws between `sole` and `shared`. A record written before 2026-09-10 carries no `billing_mode`; it is admitted on its old terms and counted separately, so this change does not silently rewrite the past.
+
+Tokens remain the unit that works everywhere, and they are what every figure is built from. `cost_usd` is whatever the provider itself reported, and `billing_mode` is what stops a reader mistaking a meter, a flat fee and an invoice for one another.
+
 ### 2.6 Per-phase effort fields (added 2026-08-31; injected by `tf-emit.sh`, never emitted by an agent)
 
 Added so the question *"what did each phase cost — in time, in tokens, on which model, with how much fan-out?"* is answerable from the streams rather than reconstructed by hand. §2 and §2.5 already carried `cmd`, `started`/`ended`/`duration_s`, the four token counters, `model`, `harness`, `tier`/`tier_model`/`routed` and `attempt`. Three things were missing, and each was missing for the same reason: it was either **self-reported** or **not represented at all**.
@@ -147,6 +175,34 @@ Added so the question *"what did each phase cost — in time, in tokens, on whic
 
 **These do not create per-feature timing.** The unit stays **the run**; §0's non-goal is unchanged. `cmd` is the phase, and a phase figure is an aggregate over runs of that `cmd` — never a per-ticket cycle time.
 
+### 2.7 `kind: "run-void"` — taking a wrong run out of the figures without deleting it (added 2026-09-09)
+
+The stream is append-only, so a run record that turns out to be **wrong** can be neither edited nor deleted — and nothing inside such a record says it is wrong, so every figure built over it is quietly polluted. §5.5.7 solved the same problem on the misses stream by adding a record kind rather than an edit. This is that answer for runs.
+
+A `run-void` names one run record and says why it should not be counted:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `kind` | `"run-void"` | the record kind |
+| `app` | string | filled by the emitter from the run it names |
+| `cmd` | string | the named run's `cmd` |
+| `started` | ISO-8601 | the named run's `started` — `cmd` + `started` is the pair the readers already key on |
+| `reason` | string | free text, required: why the record is wrong, in a sentence a reader can check |
+
+**Written only by `bash .tfcore/utils/tf-emit.sh --void-run <cmd> <started> "<reason>"`**, which refuses one that names no run on the stream (a void about nothing is a claim about nothing) and refuses a second void on the same run. Like an amend, it exits 0 either way: telemetry has no veto (§10).
+
+**What the readers must do, and `tf-metrics.sh` does:** the named record leaves **every** figure — it is never clamped, halved or guessed at — and the count of what left travels with the figures, as `runs_voided_n` with the reasons in `runs_voided`. A total offered without its exclusions is just a different wrong number (the §5.5.8 rule, one stream over). A void naming a run that is not on this stream is an **orphan**: counted as `run_voids_orphaned_n` and reported, never silently dropped, exactly as an orphaned `miss-amend` is.
+
+**What it is not.** It is not a delete and not an edit: both records stay, in order, and a reader can always see what was corrected and why. It cannot be used to remove a run whose figures are merely unflattering — the reason is on the record and a reader can check it, which is the whole protection. It is not a way to fix a number: there is no "corrected duration" field, because a figure nobody measured is not recoverable by asserting one.
+
+### 2.7b A run may not start before the last one ended (added 2026-09-10)
+
+§2.7 gave a way to **correct** a start time nobody measured, and nothing refused one — so the same mistake was made twice more on the day the correction shipped, each record beginning before the record before it ended, each quietly adding its overlap to every total that crossed it (MISS-TechieFlow-20260910-04, sorted `ignored`: it was written down and not followed). A correction mechanism with no refusal in front of it is a fix that has to be remembered, which is the definition of a rule that rots.
+
+`tf-emit.sh` now **refuses** a live `run` record for an app whose `started` precedes the latest `ended` of that app's live runs. The refusal names the record it collides with and the timestamp to use instead; nothing is appended. **Voided and backfilled records are excluded from the comparison**, which is what keeps the §2.7 repair path working: void the wrong record, then the corrected one is accepted.
+
+The one real overlap is two machines appending to the same `merge=union` stream (§6). That is declared, with `bash .tfcore/utils/tf-emit.sh runs --allow-overlap`, and never assumed — the mistake this refuses is easy to make and impossible to see afterwards, so the door is a flag rather than a fallback. FR-72; `bash tests/regression/run.sh tf_overlap`.
+
 ## 3. `docs/metrics/gates.jsonl` — one record per REQ verdict per verify run
 
 **This is the primary stream.** If only one stream survives, it is this one.
@@ -298,7 +354,7 @@ Written by `.tfcore/hooks/metrics-session.sh`, wired to the **`SessionEnd`** hoo
 | `cache_creation_tokens` | int | Σ `usage.cache_creation_input_tokens`. |
 | `cost_usd` | number \| null | **Almost always `null`.** See the limitation below. |
 
-**Known limitation — cost is not in the transcript.** Claude Code `2.x` transcripts carry token counts but no per-message dollar cost, and this framework runs on a Claude Max subscription where marginal per-token cost is not the real unit anyway. `cost_usd` is therefore emitted as `null` and *never* computed from a rate card — that would be an estimate presented as a measurement. Consequently **"cost per verified REQ" is reported in tokens, not dollars**, unless a real cost source appears. (OpenCode's `opencode stats` *does* report real cost — that is the one thing it can measure which Claude Code cannot. Wiring it in is the obvious way this field stops being `null`.)
+**Known limitation — cost is not in the transcript.** Claude Code `2.x` transcripts carry token counts but no per-message dollar cost, and this framework runs on a Claude Max subscription where marginal per-token cost is not the real unit anyway. `cost_usd` is therefore emitted as `null` and *never* computed from a rate card — that would be an estimate presented as a measurement. (Since 2026-09-10 the report does price a run from a rate card, at read time and never into a record; §2.5b is what keeps the two apart.) Consequently **"cost per verified REQ" is reported in tokens, not dollars**, unless a real cost source appears. (OpenCode's `opencode stats` *does* report real cost — that is the one thing it can measure which Claude Code cannot. Wiring it in is the obvious way this field stops being `null`.) **A caveat added 2026-09-10:** OpenCode's cost is real only where the provider is billed per token. On a provider signed in with OAuth it records `0.0`, which is true of the marginal cost and false of the money, so a session record's cost carries the same warning as a run record's — with the difference that `sessions.jsonl` has no `billing_mode` field, because it is not joinable to `runs.jsonl` on anything but time (§4, below) and would have no report to serve. Read session dollars per provider or not at all.
 
 **Known limitation — session ≠ run.** One session may span several commands, or one command several sessions. `sessions.jsonl` is **not** joinable to `runs.jsonl` on anything but time. Do not attribute a session's tokens to a single run.