@techierathore/techieflow 1.0.0

package/.tfcore/tasks/log-miss.md

@@ -0,0 +1,160 @@
+# log-miss
+
+The **20-second front door** for "you missed this". The owner says what an agent got wrong — in their own words, at the moment they notice it — and this task turns that sentence into a `misses.jsonl` record plus the matching checklist line. It **never boots the app, never reproduces anything, and never touches `src/` or `tests/`.**
+
+## Why this exists
+
+The framework had three ways to record a defect and all three were expensive. `*fix-issues` fixes it. `*triage-issues` boots the app and reproduces every issue before it writes a word. `*verify` grades a whole scope. All correct for what they do — and all far too heavy for *"the export button ignores the date filter, you missed that"*, which is how most misses are actually reported.
+
+So they were not recorded at all. They became a sentence in chat, then a Remark if the owner was patient, then nothing. **An unrecorded miss is the exact problem the miss stream exists to solve**, and the friction of "first, boot the app" is what made it unrecorded. This task removes that friction and nothing else.
+
+It is deliberately *not* a mode of `*triage-issues`: the moment logging requires a repro, it stops happening.
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- `{Description}` — the owner's own words. A sentence is enough. May name a REQ, a screen, a phase, or none of them.
+- Optional: a screenshot path, a REQ id, `--fixed` (see §6).
+
+## HARD SCOPE RULE
+
+**This task writes records and documentation. Nothing else.** You may read source to identify the owning REQ. You MUST NOT edit `src/` or `tests/`, MUST NOT boot the app, MUST NOT spawn a builder sub-agent, and MUST NOT fix the thing being reported — however obvious the one-liner. If the owner wants it fixed, that is `*fix-issues`, and you say so in the report.
+
+You also do not argue. If the owner says something was missed, it was missed. Your job is to classify it accurately, not to assess whether it was reasonable to miss.
+
+## SEQUENTIAL Execution
+
+### 0. Stamp the start time
+
+`date -u +%Y-%m-%dT%H:%M:%SZ` — this run's `started` and its `found_run_id`.
+
+### 1. Classify from what the owner said
+
+Do not ask questions you can answer from the checklist and the docs. Resolve, in order:
+
+1. **The owning REQ.** Match the description against `docs/{AppName}-Checklist.md` (and the DevGuide screen→REQ map if one exists). If the behaviour falls inside an existing REQ's scope, that is the `req_id`. **If nothing owns it, `req_id` is `null`** — that is a real and more interesting finding, not a failure to search hard enough.
+2. **`miss_class`** — the closed enum (SCHEMA.md §5.5.1). The distinction that matters most:
+   - The spec said it and the build did not do it → `missed-requirement` / `partial-implementation`, `origin_phase` = the build.
+   - The spec never said it → **`unspecified-gap`**, `origin_phase` = the authoring command. This is a *design* miss and it is the one the framework was blind to.
+   - It used to work → `regression`. It works but not as specified → `wrong-behaviour`.
+3. **`why_missed`** — which *practice* let it through (SCHEMA §5.5.6): `missing-checklist-item` (nothing covered the behaviour) · `insufficient-verify-method` (acceptance existed; no gate could catch this) · `code-audit-limitation` (never runtime-observable) · `ambiguous-acceptance` · `dependency-not-declared` · **`instruction-ignored`** (a written framework rule existed and was not honoured) · `other`. **Omit rather than guess** — but when `found_by` is `owner`/`production` this is the most valuable field on the record, so answer it. If the owner's sentence names the reason ("you were told to X"), that is usually `instruction-ignored`.
+4. **`artifact`** — `brd` / `architecture` / `uidesign` / `checklist` / `src` / `tests` / `config` / `devguide`.
+5. **`severity`** — `blocker` / `major` / `minor`, by owner-visible impact. Not by how hard it looks to fix.
+6. **`origin_phase` / `origin_agent` / `origin_run_id`** — read `docs/metrics/runs.jsonl` and find the most recent non-backfilled run whose `cmd` matches the responsible phase and whose `reqs_touched` contains the REQ. Pass its `started` as `origin_run_id`. **If you cannot find one, pass nothing** — the emitter marks the record `inferred` and nulls the model, which is the honest outcome.
+
+Ask the owner **at most one** question, and only when the classification genuinely turns on it (usually: "was this ever specified?"). In YOLO / goal mode, take the sensible reading, mark it in the report, and continue.
+
+### 2. Collapse check — never log the same defect twice
+
+```bash
+bash .tfcore/utils/tf-emit.sh --open-miss REQ-UI-014     # "<miss_id> <miss_class>", or nothing
+```
+
+If a miss is already open on that REQ with the same `miss_class`, **stop and say so**: "already logged as `MISS-…`, still open." Do not write a second record. Skip this check when `req_id` is `null`.
+
+**But do not throw away what the owner just told you.** A repeat report often carries information the first record does not — most often *why* it was missed. If the open record's `why_missed` is `null` and the owner's sentence answers it, complete the record instead of duplicating it:
+
+```bash
+bash .tfcore/utils/tf-emit.sh --amend MISS-AstroLyfe-20260828-03 why_missed instruction-ignored
+```
+
+That appends a `miss-amend` (SCHEMA.md §5.5.7) — it fills a `null` field and refuses to overwrite a value that is already there, so it can never rewrite the original classification. **Never edit `misses.jsonl` by hand** (constraint 5); if `--amend` refuses, report the refusal and leave the stream alone. Say in your report which record you completed and with what.
+
+### 3. Emit the miss
+
+```bash
+MID=$(bash .tfcore/utils/tf-emit.sh --next-miss-id)
+cat <<JSON | bash .tfcore/utils/tf-emit.sh misses
+{"kind":"miss","miss_id":"$MID","req_id":"REQ-UI-014","req_class":"UI",
+ "miss_class":"partial-implementation","artifact":"src","severity":"major",
+ "why_missed":"instruction-ignored",
+ "origin_phase":"build-phase","origin_agent":"trblazeui",
+ "origin_run_id":"<started, or omit>",
+ "found_by":"owner","found_phase":"log-miss","found_gate":null,
+ "found_run_id":"<the §0 timestamp>","failure_class":"blank-data"}
+JSON
+```
+
+`found_by` is `"owner"` unless the owner is relaying a live report, which is `"production"`. **Never write `origin_model`, `origin_harness`, `origin_confidence`, or any token/cost field** — `tf-emit.sh` resolves them from the run you named (`_metrics-emit-gate.md` constraint 10).
+
+**The owner's words never enter the record.** Closed vocabularies only; the sentence goes in the checklist Remark, where a human reads it (constraint 7).
+
+### 4. Write it into the checklist — the record is not the deliverable on its own
+
+**If the repo has no `docs/*-Checklist.md`** — a `framework` or `docs` project, or an app before `*split-brd` has run — there is nothing to demote and no row to add. **Emit the record and skip to §5**, saying so in the report (`Docs: no checklist in this repo — record only`). Do not invent a checklist, do not write the miss into `PROJECT-STATUS.md` instead (the guard hook blocks it, correctly), and do not treat the absence as a reason to skip the record: a framework's own misses are exactly as worth counting as an app's, and the stream is where they belong.
+
+Otherwise, in `docs/{AppName}-Checklist.md`:
+
+- **Existing REQ:** Status → `Needs re-verify`, % adjusted, plus a dated Remark — `⚠ miss {today}: {the owner's words, kept}` (`⚠ prod bug {today}:` when `found_by` is `production`). Demotions are always permitted; `guard-verify.sh` never blocks one. **NEVER write `Verified` from this task.**
+- **No owning REQ:** append a new row — next free ID in the right prefix — Status `Planned`, Remark `logged via *log-miss {today}`, plus a detail bullet with its `<a id="d-req-…">` anchor stating the **acceptance that would close it**. If it is genuinely new scope rather than a defect, log the row and flag `*amend-docs` in the report; do not invent BRD text here.
+
+### 5. Status gate + the run record
+
+Update `PROJECT-STATUS.md` **and** re-render `PROJECT-STATUS.html` per `_status-update-gate.md` — next command is the `*fix-issues` pointer naming the REQ. Then:
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"log-miss","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":["REQ-UI-014"],"reqs_count":1,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`build_result` is always `"not-run"` — this task never builds.
+
+### 6. `--fixed` — logging a miss that is already repaired
+
+Sometimes the owner reports a miss *after* it has been fixed ("that export bug you fixed yesterday — you should never have missed it"). Recording only the fix would lose the miss; recording only the miss would leave it permanently open.
+
+With `--fixed`, emit the `miss` as above, then close it:
+
+```bash
+FA=$(bash .tfcore/utils/tf-emit.sh --next-fix-attempt "$MID")
+cat <<JSON | bash .tfcore/utils/tf-emit.sh misses
+{"kind":"miss-fix","miss_id":"$MID","req_id":"REQ-UI-014",
+ "fix_run_id":"<started of the run that fixed it, from runs.jsonl — or omit>",
+ "fix_cmd":"log-miss","fix_attempt":$FA,"verdict_after":"Verified","reopened":false}
+JSON
+```
+
+If you can identify the run that actually did the repair, name it and the cost attaches correctly. **If you cannot, omit `fix_run_id`** — the record is costed `none`, which is exactly right: the fix happened, and what it cost is not recoverable. Do not point at a plausible-looking run to make the number appear; that is a fabricated measurement, and one of them discredits every other cost figure in the report.
+
+Do **not** demote the checklist row in `--fixed` mode — the REQ's status already reflects reality.
+
+### 7. HALT — report
+
+```
+# Miss logged — {AppName}
+{MISS-id}  {miss_class} / {artifact} / {severity}
+Why missed : {why_missed | not assessed}
+Owning REQ : {REQ-id | none — new Planned row REQ-FN-0NN}
+Attributed : {origin_phase} ({origin_agent}) — {linked to run <ts> | inferred, no run record found}
+Found by   : {owner|production}
+Docs       : checklist row {demoted to Needs re-verify | added as Planned}, PROJECT-STATUS updated
+Next       : /TechieFlow:agents:flow-master *fix-issues {AppName} {REQ-id}   (OpenCode: /flow-master)
+```
+
+Say plainly when attribution came out `inferred` — the owner should know that this miss will not appear in the per-model figures, and why.
+
+## Hard rules
+
+- **Never fix anything.** This task's deliverable is a record and a checklist line. `*fix-issues` fixes.
+- **Never boot the app or reproduce.** That is `*triage-issues`, and requiring it here is what stopped misses being logged at all.
+- **Never write `Verified`.** The ceiling here is a demotion (`guard-verify.sh` enforces it).
+- **Never name a model or a token count.** The emitter resolves attribution and cost, or writes `null`.
+- **Never free-text into telemetry.** Closed vocabularies in the record, the owner's words in the checklist Remark.
+- **Never argue with the report.** Classify it and log it.
+- **Never run git.**
+
+## Output Checklist
+
+- [ ] Owning REQ resolved from the checklist, or `req_id: null` recorded deliberately
+- [ ] `--open-miss` collapse check run (skipped only when `req_id` is null); duplicate reported instead of re-logged — and if the open record's `why_missed` was null and the owner's words answered it, completed with `--amend` rather than duplicated or hand-edited
+- [ ] `miss_class` / `why_missed` / `artifact` / `severity` chosen from the closed enums — no free text in the record; `why_missed` omitted rather than guessed, but present on any owner/production report
+- [ ] `origin_run_id` resolved from `runs.jsonl`, or deliberately omitted; **no model name written**
+- [ ] `misses.jsonl` record emitted (+ `miss-fix` if `--fixed`)
+- [ ] Checklist updated — demotion with a dated `⚠ miss` Remark, or a new `Planned` row with acceptance (or: no checklist in this repo, stated in the report, record still emitted)
+- [ ] PROJECT-STATUS `.md` **and** `.html` updated with the `*fix-issues` next command
+- [ ] `runs.jsonl` record emitted
+- [ ] Nothing under `src/` or `tests/` changed; app never booted

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

@@ -0,0 +1,143 @@
+# metrics-report
+
+## Purpose
+
+Turn `docs/metrics/*.jsonl` into a report the owner can read and, more importantly, **defend**. Produces `docs/metrics/METRICS.md` + `docs/metrics/METRICS.html`.
+
+This task answers five questions and nothing else:
+
+1. **First-pass rate** — what fraction of REQs reach `Verified` on attempt 1?
+2. **Gate catch distribution** — of all failures, which gate caught them?
+3. **Escape rate** — what fraction of defects reached UAT/production instead of being caught by a gate?
+4. **Miss attribution and rework cost** — *what* was missed, *which phase / agent / model* let it through, and *what did fixing it cost*? (SCHEMA.md §5.5)
+5. **Effort per phase** — what did each phase cost in **wall clock**, **tokens**, on **which model**, and with how much **subagent fan-out**? (SCHEMA.md §2.6, added 2026-08-31)
+
+Everything else in the report is context for those five.
+
+**Question 5 is about the RUN, not the ticket.** It is an aggregate over `runs.jsonl` grouped by `cmd`. It is emphatically **not** cycle-time-per-feature — that remains a non-goal (SCHEMA.md §0), there is no per-feature timing field, and there will not be one. "`*build-phase` runs cost a median of 26 minutes and 39k output tokens" is a phase figure. "REQ-UI-004 took two hours" is not, and nothing in the streams can honestly produce it.
+
+Read `.tfcore/telemetry/SCHEMA.md` before you start. Read `.tfcore/tasks/_metrics-emit-gate.md` if you are unsure what may be written where.
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- Optional additional repo paths for a cross-project rollup: `*metrics {AppName} /path/to/OtherApp /path/to/Third`.
+
+## SEQUENTIAL Execution
+
+### 1. Compute the figures — do the arithmetic with the tool, not by eye
+
+```bash
+bash .tfcore/telemetry/tf-metrics.sh --report . --json
+```
+
+For a cross-project view, pass every repo: `bash .tfcore/telemetry/tf-metrics.sh --rollup . /path/to/OtherApp --json`.
+
+The **effort-per-phase** block (question 5) rides in the same payload under `phases`. To read it on its own — a printed table plus the per-phase detail — use:
+
+```bash
+bash .tfcore/telemetry/tf-metrics.sh --phases .          # or --phases . /path/to/OtherApp --json
+```
+
+Same standing as `--report`: read-only, no git, agent-safe.
+
+**Use this output. Do not recompute anything by hand.** The provenance separations of §2 are enforced inside that script — it has no code path that emits a combined figure. Hand arithmetic over the raw JSONL is exactly how an indefensible number gets into a report, and it is also how "insufficient data" quietly becomes "0%".
+
+`--report` and `--rollup` are read-only and run no git. **Never run `--backfill-commits` or `--backfill-gates`** — those are owner-only, and `--backfill-commits` invokes git, which agents never do.
+
+`--json` carries `per_repo[].commit_hook`. When it is `false`, this clone has no commit-telemetry hook (`pre-commit` — the retired `post-commit` form also counts), so commit telemetry is not being written **on this machine** — the commit count is understated for a reason that has nothing to do with how the project is going. Say so in §5 "What is missing" and point at `update-framework.sh <repo>` (or the owner running `--backfill-commits`). **Do not act on it yourself**: installing the hook is a framework refresh, and backfilling it is git.
+
+If the streams are empty or the script reports nothing: say so plainly, write no report, and point at re-running `update-framework.sh` on the repo (which sets telemetry up). Do not produce a page of zeroes.
+
+### 2. THE PROVENANCE RULE — this is what the task exists to enforce
+
+`METRICS.md` must **never** print a combined **first-pass rate**, **gate catch distribution**, or **escape rate** that crosses either provenance boundary:
+
+- **live vs backfilled** — records reconstructed after the fact never pool with records written at the moment of the event;
+- **`project_type`** — `app`, `library`, and `docs` never pool with each other;
+- **attribution and cost confidence** (§5.5) — a miss whose `origin_confidence` is not `linked` never enters a per-phase / per-agent / per-model figure, and a `miss-fix` whose `cost_attribution` is not `sole` never enters a headline cost figure.
+
+Not as a merged figure. Not as a "total" row. Not as an "overall" summary line. Not as a helpfully-labelled average in the intro paragraph. Data on the wrong side of a boundary may appear in an **adjacent, labelled column** — never summed with the figure beside it.
+
+**Every exclusion is printed with the figure it bounds.** The JSON carries `misses.attribution_excluded` and the three `cost_*_n` counts for exactly this: an exclusion the reader cannot see is indistinguishable from a bug, and the reader is entitled to know that a per-model miss rate was computed over 7 of 19 records.
+
+**Any table containing backfilled data carries a footnote** naming what was reconstructed and what was inferred (`inferred[]` on the records tells you exactly which fields).
+
+**Commit-derived metrics are exempt from both separations.** `git log` is a real append-only log, and commit volume is comparable across project types.
+
+**Why this is not cosmetic.** A merged first-pass rate cannot be defended when someone asks how attempts were counted, because backfilled attempts are inferred from a mutable status table that never recorded them. A pooled gate distribution understates the visual gate, because `library` and `docs` projects never had screens to fail on. One indefensible figure contaminates every other number in the report — the reader stops trusting the page, not just the row.
+
+If you find yourself wanting to write "overall, across all projects, …" — **that sentence is the thing this task forbids.** Write the segmented figures and let them stand apart.
+
+### 3. Honesty rules for every number on the page
+
+- **Fewer than 3 supporting records → print `insufficient data (n=…)`, never a number.** A 100% first-pass rate from one REQ is noise wearing a suit.
+- **Never estimate, interpolate, or infer a metric that was not measured.** A missing number is reported as missing. `cost_usd` is `null` on every Claude Code and Codex record (no cost source exists, and inventing one would be an estimate presented as a measurement) — report **tokens**, name the harness, and say why dollars are absent. **Do not multiply tokens by a rate card.** Real dollars appear only on OpenCode records and are never pooled with the others.
+- **Measured cost and apportioned cost are two columns, never one number.** A fix run that repaired three misses has one token window; dividing it three ways is arithmetic. Print `cost_attribution:"sole"` figures as the headline and `shared:<n>` figures beside them, labelled as apportioned. `none` records are counted and costed at nothing.
+- **Never invent a metric that has no stream behind it.** No cycle-time-per-feature: the unit of work in this framework is the run, not the ticket, and that is deliberate.
+- Records with `project_type_inferred: true` are **unclassified** — give them their own row labelled as such. Do not silently fold them into `app`.
+- Name the REQs excluded from the live first-pass rate because they carry backfilled history (the tool lists them). A hidden exclusion is a lie of omission.
+- **Miss counts are poolable; miss *attribution* is not.** A miss counts as a miss whoever missed it, so raw counts and the class distribution may pool freely. The per-phase / per-agent / per-model rates run over `origin_confidence:"linked"` records only, and the excluded count is printed with them.
+- **A per-model miss rate is observational, not causal, and the page must say so once.** Which model gets the hard work is not random, and a reader who takes the ranking at face value will make a routing decision on a confounded number. **The same warning applies to per-phase effort:** `*build-phase` costing more than `*log-miss` is a fact about what those phases *are*, not a finding about either.
+- **Per-phase effort carries three denominators and all three are printed.** Token figures cover only runs whose window was computable (`tokens_measured_n` vs `tokens_unmeasured_n`); **fan-out figures cover `tokens_scope:"tree"` records only**, because a `main` window never read the subagent transcripts and its `0` means *not observed*, not *none ran*; dollars are per harness and never pooled. A phase figure quoted without its denominator is the TF-005 defect wearing a different hat.
+- **Where declared and measured fan-out disagree, the measured one is right, and say both.** `subagents` is a list an agent typed into its own emit; `subagent_runs` is counted from the harness's own store (SCHEMA §2.6). The gap between them is itself a finding about how well tasks self-report.
+
+### 4. Write `docs/metrics/METRICS.md`
+
+Use `.tfcore/templates/v4custom/metrics-report-template.md` for the shape. Fill only what the data supports; delete sections with no data rather than printing empty tables.
+
+**Never write metrics into `PROJECT-STATUS.md`** (`guard-status.sh` blocks any H2 outside the template's section set, correctly) **or into any `*-Checklist.md`** (`guard-verify.sh` inspects those writes; a stray metrics edit risks a false block). The report lives in `docs/metrics/` and nowhere else.
+
+**Do not modify any `.jsonl` file.** They are append-only history. Nothing derived is ever written back into a stream.
+
+### 5. Render `docs/metrics/METRICS.html`
+
+Per `.tfcore/tasks/generate-html.md` using the shared shell (`.tfcore/templates/v4custom/html-render-shell.md`) — theme toggle, never hand-rolled HTML. METRICS is a human doc, so it renders; the checklists still never do.
+
+### 6. HALT — report
+
+```
+# Metrics — {AppName}
+Streams: runs {r} · gates {g} ({b} backfilled) · sessions {s} · commits {c} · misses {m}
+First-pass rate: {live, per project_type — or "insufficient data"}
+Gate catch: {top gate} {n}%  |  Escape rate: {x}%
+Misses: {m} logged ({o} open) · design-miss share {d}% · attributed {a}/{m}
+Rework cost: {tokens} tokens per miss (measured, n={s}) {| $X measured, OpenCode only}
+Effort/phase: heaviest {cmd} — {time} wall, {tokens} out ({pct} of all output), fan-out observed on {n}/{N} runs
+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 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
+
+- **No combined figure across live/backfilled, across `project_type`, across attribution confidence, or across cost attribution** — for first-pass rate, gate catch distribution, escape rate, miss rates, or cost per miss. This is the rule the whole task exists for.
+- **The miss stream's escape share is reported BESIDE the `gates.jsonl` escape rate, never merged into it.** They are computed from different records by different definitions; presenting one number for both would make the word meaningless.
+- **Never run git**, and never run `tf-metrics.sh --backfill-*` — owner-only.
+- **Never write into `PROJECT-STATUS.md`, any `*-Checklist.md`, or any `.jsonl` stream.**
+- **`insufficient data` is a legitimate result.** Print it without apology and without a workaround.
+- **Never store or quote requirement text** pulled from a checklist to "make the report readable". REQ IDs only — the constraint that governs the streams governs the report built from them.
+- Do not refactor the streams, re-sort them, or "clean up" a malformed line. Report the line number and move on.
+
+## Output Checklist
+
+- [ ] `tf-metrics.sh --report --json` run; figures taken from it, not recomputed by hand
+- [ ] Live and backfilled reported separately; `app`/`library`/`docs` reported separately
+- [ ] Miss attribution figures computed over `linked` records only, with the excluded count printed beside them
+- [ ] `why_missed` distribution reported against **records that carry the field** *and* could have carried it — misses predating the field's introduction (`FIELD_SINCE`, SCHEMA §5.5.6) are outside the denominator and their count is stated; escapes lacking it are flagged, with `--amend` named as the remedy
+- [ ] `miss-amend` records folded into their parents before counting; amendments applied and orphaned amends both reported
+- [ ] Open-miss count excludes `wont-fix` (a decision, not a backlog item) and reports it in its own bucket
+- [ ] Measured (`sole`) and apportioned (`shared:n`) rework cost in separate labelled columns — never one blended number
+- [ ] Rework-cost means divide by the records that **carry** `tokens_out` (`tokens_per_miss_measured_n`), with `tokens_unrecorded_sole_n` stated — an unrecorded repair is never averaged in as a free one (SCHEMA §5.5.8)
+- [ ] Effort-per-phase section written from `phases` — per-phase wall clock, tokens, **per-model output split**, and subagent fan-out
+- [ ] Every per-phase token figure carries `tokens_measured_n` / `tokens_unmeasured_n`; every fan-out figure carries `fanout.observed_n` and names why the rest were excluded (not `tree` scope vs predating the field)
+- [ ] Declared (`subagents`) and measured (`subagent_runs`) fan-out both shown where they disagree, with the measured one named as authoritative
+- [ ] No per-feature or per-REQ cycle time anywhere on the page — the unit is the run
+- [ ] Dollars quoted only where a harness measured them; no rate-card estimate anywhere on the page
+- [ ] No "overall" / "total" / "combined" figure for first-pass rate, gate distribution, or escape rate
+- [ ] Every table containing backfilled data carries the inferred-fields footnote
+- [ ] Metrics with n < 3 printed as `insufficient data (n=…)`
+- [ ] Excluded (backfill-tainted) REQs named
+- [ ] `docs/metrics/METRICS.md` written + `METRICS.html` rendered via the shared shell
+- [ ] No `.jsonl` file touched; PROJECT-STATUS and the checklist untouched

package/.tfcore/tasks/mockups.md

@@ -0,0 +1,122 @@
+# mockups
+
+Produce the **UI design / mockups** for a greenfield app: a per-screen UI Design Spec (`docs/{AppName}-UIDesign.md`) plus **rendered HTML mockups** (`docs/mockups/*.html`) styled to look like TrBlazeUI, each annotated with a `region → TrBlazeUI control` component map. This is the visual design the build is matched against and the verifier's visual-truth gate diffs the live app against.
+
+## Why this exists
+
+A greenfield app has no code, so its UI is built freehand from prose requirements — which is exactly why a new app's UI comes out broken (overlapping controls, wrong layout, nothing to verify against). Mockups give the build an **approved visual contract** and give `verify-phase.md §4b` a **baseline to diff** the running screen against. They are **TrBlazeUI-replicable by construction**: the analyst designs only with controls the library actually ships, so `/trblazeui` can reproduce them 1:1.
+
+## When to use
+
+- **At greenfield day-1** — auto-run by `day1-greenfield §3.6`, after the BRD draft; approved with the BRD + Architecture before build.
+- **On demand** — `*mockups {AppName}` to (re)generate, or `*mockups {AppName} --update` to refresh only changed/new screens after an `*amend-docs` that added UI.
+- **Greenfield only.** Brownfield already has built screens — it uses the DevGuide's captured screenshots (`devguide §5a/§5b`) as its visual baseline instead.
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- `{Scope}` — OPTIONAL: `all` (default) · a screen/route · a comma-list. Limits which screens are (re)mocked.
+- `--update` — OPTIONAL: refresh only screens whose BRD feature changed or that are new; preserve unchanged mockups verbatim.
+
+## SEQUENTIAL Execution
+
+### 1. Read the TrBlazeUI component catalog FIRST (design only with what exists)
+
+Before designing anything, learn what the library actually provides:
+- Read `.trblazeui/TrBlazeUI-AI-Reference.md` (the component reference; if absent, run `dotnet build` once to deploy it, or ask the `/trblazeui` agent for its component catalog).
+- Optionally converse with the **`/trblazeui` agent** to confirm which controls exist and how they're composed (it owns the library knowledge).
+- Build a working list of available controls (nav, cards, grids, forms, dialogs, charts, layout shells, inputs). **You design ONLY with these** — a mockup that uses a layout/control TrBlazeUI can't produce is worse than none (it guarantees drift). If a screen genuinely needs something the library lacks, note it and log a `docs/{AppName}-TrBlazeUI-Feedback.md` entry (TR-NNN) so the gap is tracked rather than silently designed-in.
+
+### 2. Derive the screen list from the BRD
+
+- Read `docs/{AppName}-BRD.md` §9 Feature catalog — its screens-and-routes tables and per-feature workflows are the screen list. Also read `docs/{AppName}-Architecture.md` for the UI host/layout choice.
+- Produce the flat screen list: `screen (route) → role(s) → owning BRD-N`. Echo a one-line count: `N screens to mock`.
+- **No-UI app:** if the concept is purely an API/service with no screens, record `docs/{AppName}-UIDesign.md` = "skipped — no UI in this app" and HALT (this is not an error; `day1-greenfield` treats it as skipped).
+
+### 3. Design each screen — spec + rendered mockup (FAN OUT for many screens)
+
+Load `.tfcore/templates/v4custom/app-uidesign-tmpl.md`. For each screen (fan out across subagents when there are many — one per screen-cluster — to bound tokens):
+
+1. Decide the **layout** (regions: nav, sidebar, content blocks) using TrBlazeUI's layout shell components.
+2. Write the **component map** — every region → the specific TrBlazeUI control that renders it + the data it shows + its empty/loading/error states. This is the build contract.
+3. Produce the **rendered mockup** `docs/mockups/{screen-slug}.html`: a self-contained HTML page that *looks like the real screen* using TrBlazeUI's design language (its CSS tokens / classes where known, or a close visual approximation — spacing, colors, typography, component shapes). Use realistic placeholder data so the layout reads true. Each mockup is a static preview, not wired — but its STRUCTURE (regions, control types, arrangement) must be what the build will produce.
+4. Fill the screen's spec block in `docs/{AppName}-UIDesign.md` (mockup link, component map table, layout one-liner, interaction + state notes).
+
+Keep the visual language consistent across screens (one shell, one theme, one spacing system) so the set reads as one app.
+
+#### 3b. ANCHOR THE MOCKUP — `data-testid` is what makes it gradeable (MANDATORY since 2026-08-31)
+
+A mockup is not only a picture for the owner to approve. Since 2026-08-31 it is **the input to a gate**: `verify-phase` §4b2 compares the built screen against it mechanically, and **it can only compare elements that carry the same `data-testid` on both sides.**
+
+**Put a `data-testid` on every element the build must get right**, using the same name the built component will carry:
+
+- the layout regions — `app-sidebar`, `app-header`, `main` (match the shell's real names; a mockup that says `sidebar` where the app says `app-sidebar` pairs with nothing and grades nothing);
+- every **badge, pill, chip and status indicator** — these are the single most-escaped class, because a pill flattened to plain text still *has text* and passes every other gate;
+- every **icon or icon button**;
+- each **KPI tile / card**, individually — especially two adjacent cards the design distinguishes (a dashed border meaning *estimate* beside a solid one meaning *measured* is a real distinction the gate now reads, and it can only read it on an anchored element);
+- each **table** and each **chart**;
+- any value cell whose **width is part of the design** — a formatted number that must not break mid-digit.
+
+**Why this is worth the keystrokes, stated plainly.** The gate's depth is bounded by what both sides anchor, and the failure mode is **silent and inverted: the less of a screen the gate can see, the cleaner its verdict looks.** A screen the gate cannot reach into does not report "I could not grade this" as a defect — it reports `UNGRADEABLE`, which is honest but buys nothing. Upstream, three columns anchored only at the container level yielded three coarse comparisons and a `PASS`, while a human then found two structural defects on that same screen by eye (TfLens **TF-011**).
+
+Two things make this cheaper than it sounds:
+
+- **The walker descends any anchored subtree** — card, column, grid, `<dl>`, list, table alike — so an anchor on a *container* now buys real depth, not just one comparison. You do not need an id on every leaf.
+- **The gate tells you what is missing.** Each screen's run output carries `anchor_deficit.add_data_testid_to_mockup`, naming the app testids the mockup lacks. Closing the gap later is a mechanical edit — but doing it here is free.
+
+**Do not invent ids the build will not use.** An anchor that pairs with nothing is worse than no anchor: it costs effort and grades nothing. Take the names from the component map you just wrote in step 2, and use the same ones in `*build-phase`.
+
+### 4. Assemble + render
+
+- Fill the UIDesign header (§"Design system" from §1's catalog — name the layout shell, theme, and the controls inventory the app uses).
+- Regenerate the UIDesign Table of Contents (slug rule `html-render-shell.md §1`; list each `### Screen:` under "Screens").
+- Render `docs/{AppName}-UIDesign.md` → `docs/{AppName}-UIDesign.html` via `.tfcore/tasks/generate-html.md` (shared shell — it's a human doc). The `docs/mockups/*.html` screens are already HTML; leave them as-is.
+- **`--update`:** only (re)write changed/new screens + their mockups; preserve the rest verbatim; re-render the UIDesign HTML.
+
+### 5. PROJECT-STATUS note (light touch — NOT the full gate)
+
+Add/refresh one line under "Where I am" / artifacts: `Mockups generated {date}: docs/{AppName}-UIDesign.md (+ .html) + docs/mockups/ ({N} screens)`. This task does not change build/verify state — do not touch `current_phase` or `last_verified_build`. (When run inside `day1-greenfield`, that task owns the status write.)
+
+### 5a. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"mockups","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+### 6. HALT — report
+
+```
+# Mockups — {AppName}
+Screens mocked: {N}   TrBlazeUI controls used: {list}   Library gaps logged: {g}
+Files: docs/{AppName}-UIDesign.md (+ .html) · docs/mockups/*.html ({N} screens)
+Next: review/approve the mockups (open docs/mockups/*.html); they are the visual contract the build matches and the verifier diffs against. Then *split-brd → *build-phase.
+```
+
+## Hard rules
+
+- **TrBlazeUI-replicable only.** Read the component catalog first; design with controls that exist. A mockup the library can't produce is a defect — flag + log the gap, never design it in silently.
+- **Every screen has a component map** (`region → TrBlazeUI control`). The map is the build contract; a pretty picture with no control mapping is not enough.
+- **Mockups are a HUMAN doc → rendered to HTML.** Unlike the checklist, the UIDesign spec renders to HTML; the mockups are HTML by construction.
+- **Greenfield only.** Do not run for a brownfield app with built screens (use the DevGuide screenshots instead).
+- **Never edit source code.** This task only writes the design docs/mockups.
+- **Incremental on `--update`.** Preserve unchanged screens verbatim; only remock what changed.
+
+## Output Checklist
+
+- [ ] TrBlazeUI component catalog read FIRST; design uses only existing controls (gaps logged to the feedback file)
+- [ ] Screen list derived from BRD §9 feature catalog (or "skipped — no UI" recorded)
+- [ ] `docs/{AppName}-UIDesign.md` written: per-screen spec with a `region → TrBlazeUI control` component map + state notes
+- [ ] `docs/mockups/{screen}.html` rendered for every screen, styled to look like TrBlazeUI, consistent across the set
+- [ ] **Every mockup anchored with `data-testid` (§3b)** — layout regions under the shell's real names, plus every badge/pill, icon, KPI tile, table, chart and width-critical value cell. Ids taken from the §2 component map so they pair with what the build will render. Without them `verify-phase` §4b2 returns `UNGRADEABLE`, which is not a pass.
+- [ ] `docs/{AppName}-UIDesign.html` rendered (human doc); mockups left as HTML; the checklist is NOT involved here
+- [ ] PROJECT-STATUS got the one-line mockups note (no full status gate)
+- [ ] Report printed; mockups ready for owner approval

package/.tfcore/tasks/productguide.md

@@ -0,0 +1,105 @@
+# productguide
+
+Generate (or incrementally refresh) the **end-user Product Guide** — the screenshot-illustrated, task-oriented manual that teaches an *external user* how to use the app, screen by screen. It is the user-facing sibling of the DevGuide: same screen inventory and the **same captured screenshots**, but re-told as "what this is for / how to do it" instead of code lineage.
+
+Output: `docs/{AppName}-ProductGuide.md` (single doc, small apps) **or** a `docs/productguides/` subfolder with an index + one `docs/productguides/{AppName}-ProductGuide-{Role}.md` per role (large apps) — **always with a sibling `.html`** (it is a human-facing doc, so MD + HTML are both mandatory, every time). Template: `.tfcore/templates/v4custom/app-productguide-tmpl.md`.
+
+## When to use
+
+- **Whenever you need user-facing documentation** — for onboarding, a help site, a manual, app-store/marketing copy, or handing the product to non-technical users. On-demand by design (`*productguide {AppName}`).
+- **Re-runnable**: `--update` refreshes only changed screens (and re-shoots their screenshots) — cheap to keep current as the UI evolves.
+- It is purely a documentation task — it **never edits source code**.
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- `{Scope}` — OPTIONAL: `all` (default) · a role name · a screen/route · a comma-list. Limits which screens are (re)written.
+- `--update` — OPTIONAL: incremental refresh — only re-write screens whose UI changed since the guide's last generation (or only `{Scope}`), preserving every unchanged section verbatim.
+- `--single` / `--split` — OPTIONAL: force the structure instead of auto-deciding (same rule as devguide §3).
+
+## SEQUENTIAL Execution
+
+### 1. Confirm there is a built, runnable UI
+
+The Product Guide documents the real running app. If the repo is doc-only / not yet built (e.g. greenfield before any build), HALT: "No built UI yet — the Product Guide documents the running app with real screenshots. Build first, then run `*productguide {AppName}`." (A greenfield app gets its Product Guide AFTER it is built, exactly like its DevGuide.)
+
+### 2. Gather the screen inventory + screenshots (reuse, don't reinvent)
+
+The DevGuide already did the hard discovery work — reuse it:
+- Read the **DevGuide** (`docs/{AppName}-DevGuide.md`, or the split set under `docs/devguides/`) for the role→menu map, the screen list, the real post-login landing per role (LANDING-TRUTH), and each screen's purpose.
+- Use the **screenshots** the DevGuide's OBSERVE pass captured under `docs/screenshots/{AppName}/` (`{role}-{screen-slug}.png`, + `-mobile` where present). These are the images the guide embeds.
+- Read the **BRD** §9 feature catalog (feature purpose/benefit, personas) and the **UsageGuide** (user flows + known limitations) for the plain-language "what it's for" and "tips".
+
+**If screenshots are missing or stale** (no DevGuide ran OBSERVE, or the UI changed): capture them yourself before writing — boot the app and screenshot each in-scope screen via the **verifier render sweep** (`.tfcore/tasks/verify-phase.md §4a`, the same mechanism devguide §5a uses), saving to `docs/screenshots/{AppName}/`. Follow `.tfcore/tasks/_smoke-test-policy.md` (you run it yourself; bring up multi-service stacks; documented test users; "can't run on Linux" is banned). If the app genuinely cannot be booted after the full escalation, HALT and tell the user to bring the stack up — a Product Guide with no real screenshots is not acceptable (do NOT fabricate images or ship a screenshot-less guide silently).
+
+### 3. Decide structure — single doc vs per-role split
+
+Same rule as devguide §3: **split per role** when `roles ≥ 3` OR `screens > 12` OR any role has `> 8` screens; else single. Honor `--single`/`--split`. A split guide lives in `docs/productguides/` (index + per-role files co-located, so relative links resolve); a single guide is `docs/{AppName}-ProductGuide.md`. On a structure switch (single↔split), move/delete the stale-location copy so only one canonical copy survives.
+
+### 4. Write the guide — END-USER voice, screenshot per screen (FAN OUT per role)
+
+Fan out one subagent per role (or screen-cluster) to bound tokens, each scoped to its slice. From the template, for each in-scope screen write a `### {Feature / Screen}` block:
+- **What it's for** — the user benefit in plain language (from the BRD feature catalog), NOT code or architecture.
+- **How to use it** — numbered, task-oriented steps a real user follows (click X, enter Y, see Z), in navigation order.
+- **The real screenshot** — embed `![{screen}](<rel>/screenshots/{AppName}/{role}-{screen-slug}.png)` (path relative to where the guide lives: `screenshots/...` from `docs/`, `../screenshots/...` from `docs/productguides/`).
+- **Tips & notes** — gotchas/limits in plain language (translate any UsageGuide "known limitation" into user terms; never expose REQ/defect IDs or internal jargon).
+
+Order screens the way a user would actually move through them (the DevGuide menu map). Omit pure-plumbing/internal screens an external user never sees (unless writing the admin-role guide). Fill the template header (Welcome, Getting started with the sign-in shot, Roles at a glance) from the BRD + DevGuide.
+
+**Voice rule:** this is for someone who has never seen the code and may not be technical. No file paths, no service/proc names, no REQ IDs, no architecture. If a sentence would only make sense to a developer, it belongs in the DevGuide, not here.
+
+For `--update`: locate the existing guide (either layout), re-write only changed/in-scope screens (re-shoot their screenshots), preserve the rest verbatim.
+
+### 5. Render to HTML (MANDATORY — both MD and HTML, every time)
+
+Render every produced markdown to a sibling `.html` via `.tfcore/tasks/generate-html.md` (shared shell — light/dark theme, TOC). The Product Guide is a human-facing doc, so **MD + HTML are both required**; a markdown-only Product Guide is an incomplete deliverable. For a split guide, render the index + every role file in place inside `docs/productguides/`. (The checklist is the only doc that stays markdown-only; this is not that.)
+
+### 6. Note it in PROJECT-STATUS (light touch — NOT the full gate)
+
+Add/refresh one line under "Where I am" / artifacts: `Product Guide generated {date}: docs/{AppName}-ProductGuide.md (single) or docs/productguides/ (split) (+ .html); {M} screens, {S} screenshots`. This task does not change build/verify state — do not touch `current_phase` or `last_verified_build`. Re-render `PROJECT-STATUS.html` only if you edited it.
+
+### 6a. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"productguide","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+### 7. HALT — report
+
+```
+# Product Guide — {AppName}
+Structure: {single | split per role (R files)}
+Roles: {list}   Screens documented: {M}   Screenshots used/captured: {S} (existing {e} / newly captured {c})
+Files: docs/{AppName}-ProductGuide.md (single) — or docs/productguides/{AppName}-ProductGuide.md + -{Role}.md ... — and sibling .html (always)
+Next: open the .html in a browser; run `*productguide {AppName} --update` after UI changes.
+```
+
+## Hard rules
+
+- **End-user voice, never developer.** No code paths, service/proc names, REQ/defect IDs, or architecture. If it only makes sense to a developer, it's not Product-Guide content.
+- **Every screen carries a REAL screenshot** (reused from the DevGuide's `docs/screenshots/{AppName}/`, or freshly captured via the verifier render sweep). Never fabricate an image; never ship a screenshot-less guide silently — HALT and ask for the app to be booted if capture genuinely fails.
+- **MD + HTML always.** This is a human-facing doc; both versions are mandatory on every run (unlike the checklist, which is markdown-only).
+- **Never edit source code.** Documentation only.
+- **Reuse the DevGuide's discovery + screenshots** rather than re-deriving the screen map — they share the same screen inventory (developers' view vs users' view of the same screens).
+- **Incremental by default on `--update`.** Preserve unchanged screens verbatim; only re-write + re-shoot what changed.
+- **Boot the app yourself if screenshots are missing** (incl. multi-service stacks; documented test users) per `_smoke-test-policy.md`; asking the user is the last resort. Never run git.
+
+## Output Checklist
+
+- [ ] Built UI confirmed (HALT if doc-only / not yet built)
+- [ ] Screen inventory + screenshots reused from the DevGuide (`docs/screenshots/{AppName}/`), or freshly captured via the render sweep where missing/stale
+- [ ] Structure decided (single vs split per role) with stated reason / honored `--single`/`--split`
+- [ ] Each screen block: plain-language "what it's for" + numbered "how to use it" + a REAL screenshot + tips — END-USER voice (no code/proc/REQ-ID/architecture)
+- [ ] Header sections (Welcome, Getting started w/ sign-in shot, Roles at a glance) filled from BRD + DevGuide
+- [ ] **Both MD and HTML produced** (index + role files if split) — HTML is mandatory, not optional
+- [ ] PROJECT-STATUS got the one-line Product Guide note (no full status gate)
+- [ ] Report printed with structure, counts, screenshots used/captured