@techierathore/techieflow 1.0.2 → 1.0.3

package/.tfcore/tasks/fix-issues.md

@@ -1,134 +1,15 @@
 # fix-issues
 
-The single front door for fixing bugs the owner found by running the app — UI layout, broken rendering, wrong data, or logic. You drop **a folder of screenshots (+ an optional description file)**; flow-master reproduces each issue, triages where it lives, fans the fix out to the right builder, re-verifies, and updates the docs. **You never invoke the UI / functional / RAG agents yourself — flow-master calls them as sub-agents.**
+`*fix-issues {App} {folder}` is the one command the owner hands a pile of evidence to: a folder of screenshots with an optional notes file. It reproduces each bug, logs it, fixes it through the builders, re-verifies the touched rows and closes the misses with the cost of the fix. The owner never calls a builder. If the owner's words ask only to analyse or log, this is `*triage-issues`, not a fix. It honours YOLO.
 
-## Why this exists
+First: `bash .tfcore/utils/tf-phase.sh start fix-issues {App}` prints the start time; keep it. The marker is what lets a migration run from this command.
 
-When the verifier passes but the running UI is still broken (overlapping controls, blank screens, wrong behavior), the owner needs ONE command to hand a pile of evidence to and have it fixed end-to-end — not to choreograph trblazeui, techierag, and the verifier by hand. `*fix-issues` is that command. It is generic: a bug can be anywhere (layout, data, logic, RAG), so it triages first and routes second. (Analysis WITHOUT fixing — "log these UAT bugs, don't fix yet" — is `*triage-issues`, not this task; see §0.)
+## Steps
 
-## Inputs
-
-- `{AppName}` (required; or resolve from `core-config.yaml`).
-- `{Folder}` (required) — a path to a folder the owner filled with **screenshots** of the broken screens and, optionally, a **description file** (`bugs.md` / `README.md` / `notes.txt`) naming what's wrong on each (e.g. "Dashboard: KPI cards overlap the chart; Clients list shows count 16 but rows are blank"). If `{Folder}` is omitted, ask once for the folder path. (Screenshots-in-a-folder is the intended evidence channel — do not require the owner to describe bugs in chat.)
-
-## SEQUENTIAL Execution
-
-### 0. Scope guard — was a FIX actually requested?
-
-**`*fix-issues` fixes.** If the owner's words ask only to **analyze / triage / log / document** the bugs, update the checklist, or re-verify other features — and do NOT ask for a fix — STOP: execute `.tfcore/tasks/triage-issues.md` instead (same evidence channel, docs-only deliverable) and let the owner decide about fixing afterwards. "Analyze these bugs" is NEVER permission to edit code.
-
-### 1. Ingest the evidence
-
-- List the folder. **Read every screenshot** (vision) and the description file if present. Build a working list of issues: `{ id, screen/route guess, role guess, symptom, evidence-image }`.
-- For each issue, classify a first-guess **kind**: `layout` (overlap/clip/off-viewport/unstyled), `render-empty` (blank table/chart/value), `data/logic` (wrong values, failed action), `rag` (bad/empty AI answer). Final classification happens after repro (§3).
-- If the description names screens/roles, use them; otherwise infer the screen from the screenshot (match against the DevGuide screen list / routes).
-
-### 2. Boot the app (per `_smoke-test-policy.md` + `verify-phase.md §Local-only`)
-
-- Boot the app yourself via the build-invocation-ladder; bring up dependent services (DB/LLM/API) in dependency order for a multi-service stack. "Can't run on Linux / it's multi-service / it targets Windows" are BANNED excuses; escalate per `verify-phase.md §3a` (rung #4 Windows-side → another port → ask the owner only as a last resort). Never propose a cloud deploy.
-- Resolve a test login from `docs/{AppName}-UsageGuide.md` / the DB — never auto-create a random user.
-
-### 3. Reproduce each issue live with Playwright
-
-For each issue, log in as the relevant role, navigate to the screen, and **reproduce the symptom**:
-- Take a fresh screenshot at desktop + a mobile width and compare to the owner's evidence.
-- Apply the **data render gate** (`verify-phase.md §4a`) and the **visual-truth gate** (`§4b`): is the control blank? do controls overlap / clip / sit off-viewport? is it unstyled?
-- Settle the issue's **kind** from what you observe (not just the owner's guess), and map it to the owning screen + `REQ-*` in `docs/{AppName}-Checklist.md` (use the DevGuide screen→REQ map). If an issue can't be reproduced, note it (maybe environment/data-specific) and ask the owner rather than guessing a fix.
-
-Echo a triage table before fixing:
-```
-Issue 1 → REQ-UI-007 (Dashboard) — kind: layout (KPI cards overlap chart @ both widths) → /trblazeui
-Issue 2 → REQ-FN-014 (Clients)   — kind: render-empty (grid 16 count, 0 rows)         → flow-master (data) 
-Issue 3 → REQ-RAG-003 (Assistant)— kind: rag (empty answer)                            → /techierag
-```
-
-### 4. Fan out the fixes to the right builder (flow-master calls them — the owner does not)
-
-In ONE turn, route each issue to its builder as a sub-agent, in parallel where they don't share files:
-- **`layout` / UI** → invoke **`/trblazeui`** as a sub-agent: fix the Razor/CSS/component so it renders correctly and matches the mockup (greenfield) / intended layout; cite the REQ + the symptom + the screenshot. Page-layout fixes are trblazeui's job.
-- **`render-empty` / `data` / `logic`** → spawn a **builder subagent** (`tf-builder` if the harness registers it, otherwise the harness's general subagent — Claude Code `Agent` tool / OpenCode `task` tool): fix the binding/guard/column-mapping/service/query so the control actually renders its data (the `verify-phase §4a` failure modes — undeclared params, column→property mismatch, throwing computed getters, null guards).
-- **`rag`** → invoke **`/techierag`** as a sub-agent: fix the RAG flow (ingestion/search/prompt/provider config).
-- Each sub-agent tags its fix with the `[REQ-*]` tag in the checklist Remarks (**NEVER a git commit — git is manual; agents never run git/gh**), logs any library gap to the owning feedback file, and returns `{ reqsFixed[], filesChanged[], notes[] }`. Every sub-agent prompt MUST carry the two standing rules from `build-phase.md §3` verbatim (no git; smoke it yourself — library agents don't read `.tfcore/` tasks). Wait for all to return.
-
-### 5. Re-smoke (data + visual) then re-verify the affected REQs
-
-- Rebuild (invocation ladder). Re-smoke each fixed screen yourself: data renders AND it looks right at desktop + mobile (per `_smoke-test-policy.md` — both gates). If a fix didn't take, loop back to §4 for that issue.
-- Chain the verifier: read `.tfcore/tasks/verify-phase.md` and run it inline scoped to the affected REQ IDs (skip its §0 question — scope is known). It applies §4a + §4b and writes verdicts into `docs/{AppName}-Checklist.md`.
-
-### 6. Update the docs (status gate)
-
-- **Checklist:** the verifier already wrote verdicts; confirm each fixed REQ is `Verified` (or note why not).
-- **DevGuide:** refresh the affected screens' observed render/visual status + Known issues (the verifier's §6b does this; if a screen wasn't in scope, update it via `*devguide {AppName} --update`).
-- **PROJECT-STATUS (FINAL GATE, per `_status-update-gate.md`):** update `PROJECT-STATUS.md` AND re-render `PROJECT-STATUS.html` — open requirements, a verification-log row, next command. A markdown-only update is incomplete.
-- **Never run git.** Investigate by reading working-tree files at `file:line`, never a diff.
-
-### 6a. Emit the run record — and CLOSE the misses you fixed
-
-Same turn as the status gate. Doctrine: `.tfcore/tasks/_metrics-emit-gate.md`; schema `.tfcore/telemetry/SCHEMA.md` §2 + §5.5. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` at §1, before you ingest anything.
-
-**Emit the run record FIRST.** The `miss-fix` records below carry no numbers of their own — they name this run, and `tf-emit.sh` copies its token window. A `miss-fix` emitted before its run record finds nothing and is costed `none`.
-
-```bash
-cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
-{"kind":"run","app":"{AppName}","cmd":"fix-issues","mode":"fix",
- "started":"<start>","ended":"<now>","duration_s":<n>,
- "reqs_touched":["REQ-UI-009"],"reqs_count":1,
- "subagents":["trblazeui"],"files_written":<n>,"build_result":"pass"}
-JSON
-```
-
-`mode` is always `"fix"` here — that is the whole point of this command. The verifier chained in §5 emits its own `gates.jsonl` and `misses.jsonl` records; do not emit those yourself.
-
-**Then one `miss-fix` per REQ you repaired.** This is what makes "what did that miss cost to fix" answerable at all:
-
-```bash
-for REQ in REQ-UI-009 REQ-FN-014; do
-  MID=$(bash .tfcore/utils/tf-emit.sh --open-miss "$REQ" | cut -d' ' -f1)
-  [ -z "$MID" ] && continue          # no open miss for this REQ — nothing to close
-  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",
- "fix_run_id":"<the §1 start timestamp>","fix_cmd":"fix-issues",
- "fix_attempt":$FA,"verdict_after":"<the verifier's verdict>","reopened":false}
-JSON
-done
-```
-
-- **`verdict_after` is the verifier's verdict from §5, not your assessment of your own fix.** `Verified` only where the verifier actually wrote it. A miss closed on the fixer's word is the same failure as a self-attested `Verified`.
-- **A REQ with no open miss is normal** — the owner reported something the gates never recorded as a miss. Open one first (`--next-miss-id`, `found_by:"owner"`, per `triage-issues` §6a) and then close it in the same run, so the defect has both a cause and a cost.
-- **Write no token, dollar, or `cost_attribution` field.** `tf-emit.sh` copies the window from `fix_run_id` and derives the attribution from that run's `reqs_touched` — `sole` when this fix touched one REQ, `shared:<n>` when it touched several. That distinction is the whole reason the cost figure can be defended, and it is not yours to assert (constraint 10).
-
-**Telemetry has no veto:** a failed emit never changes the outcome and is not worth reporting.
-
-### 7. HALT — report
-
-```
-# Fix-issues — {AppName}
-Evidence: {Folder} ({S} screenshots, {desc|no} description)
-Issues: {N} triaged → {u} UI/layout, {d} data/render, {r} RAG, {x} could-not-reproduce
-Fixed + re-verified: {f} REQs now Verified  |  Still open: {o} (reason)
-Docs: checklist + DevGuide + PROJECT-STATUS updated (+ HTML re-rendered)
-Next: {if open issues → re-run *fix-issues with the still-broken shots / *verify all ; else "all reported issues fixed and re-verified"}
-```
-
-## Hard rules
-
-- **A fix must be ASKED for.** Analyze/log/document-only requests route to `.tfcore/tasks/triage-issues.md` (§0) — never start fixing on an analysis request.
-- **One front door, flow-master routes.** The owner runs only `*fix-issues`; flow-master calls trblazeui / techierag / its own subagents. Never tell the owner to invoke a builder agent themselves.
-- **Triage from what you OBSERVE, not just the owner's words.** Reproduce live before fixing; classify by the actual data + visual gates.
-- **Both gates before "fixed".** A fix is done only when the screen renders its data AND looks right (no overlap/clip/off-viewport), confirmed by re-smoke + the verifier.
-- **Boot the app yourself**, incl. multi-service stacks; asking the owner to run it is the last resort. Never propose a cloud deploy.
-- **Use documented test users; never auto-create random ones.**
-- **Status gate is the last action** — PROJECT-STATUS `.md` AND `.html`. Never run git.
-
-## Output Checklist
-
-- [ ] Evidence folder ingested — screenshots read (vision) + description parsed; issue list built
-- [ ] App booted (incl. dependent services); documented test user used
-- [ ] Each issue reproduced live and triaged (kind + owning REQ) — triage table echoed
-- [ ] Fixes fanned out to the right builder (trblazeui / flow-master subagent / techierag) — owner did NOT invoke any agent
-- [ ] Re-smoked (data + visual) and verifier re-run on the affected REQs (verdicts in the checklist)
-- [ ] DevGuide affected screens refreshed; PROJECT-STATUS.md + .html updated (status gate)
-- [ ] `runs.jsonl` record emitted with `cmd:"fix-issues"`, `mode:"fix"` (§6a) — **before** the miss-fix records, so the token window exists to copy
-- [ ] One `misses.jsonl` `miss-fix` per repaired REQ that had an open miss, carrying the verifier's verdict — no token/cost/attribution field written by hand
-- [ ] Report printed with fixed vs still-open counts
+1. Triage first, as `.tfcore/tasks/triage-issues.md` steps 1 to 4: read the evidence, boot (`tf-verify-boot.sh start`), reproduce each issue on its screen with the screens script, map it to its row, and log it with `tf-triage.sh demote` or `new`. Then `bash .tfcore/utils/tf-triage.sh {App} close --started <the step-0 time> --cmd fix-issues` writes the escaped gate records and the misses with the discovery cost. A defect nobody logged has no miss to close, so this step is never skipped.
+2. `bash .tfcore/utils/tf-build-list.sh {App} --prompts` now prints FIX mode with the demoted rows, their clusters and one builder prompt each. Spawn every cluster in one turn, exactly as `.tfcore/tasks/build-phase.md` step 2 says: `[trblazeui]` through `/trblazeui`, `[techierag]` through `/techierag`, the rest through the builder sub-agent. A library gap goes into the library's feedback file and the row becomes `Blocked`; never a workaround.
+3. `bash .tfcore/utils/tf-build.sh` until PASS, then smoke every fixed screen with `tf-verify-screens.sh --screen …` (`.tfcore/tasks/_smoke-test-policy.md`); a screen that still fails re-enters step 2 for its rows.
+4. Execute `.tfcore/tasks/verify-phase.md` inline, scoped to the touched rows. Only that run writes `Verified`.
+5. `bash .tfcore/utils/tf-verify-boot.sh stop`, then `bash .tfcore/utils/tf-fix-close.sh {App} --started <the step-0 time> --subagents <what was fanned out> --build <pass|fail>`: the fix-issues run record first, then one miss-fix per touched row with the verifier's verdict from the ledger. A row the verifier left below `Verified` stays open with that verdict on its miss-fix.
+6. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record is the one step 5 wrote. When this run is the last step of a goal, write the sentinel (`.tfcore/tasks/_yolo-mode.md`).
+7. Report: evidence read, issues by kind, rows fixed and now `Verified`, rows still open and why, library gaps logged, and the next command from the gate.

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

@@ -1,160 +1,21 @@
 # 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
+`*log-miss {App} "sentence" [REQ] [--fixed]` is the twenty-second record: the owner says what an agent got wrong, in their own words, and it becomes one miss record, one line in `docs/{App}-Misses.md` and one checklist line. It never boots the application, never reproduces, never edits code, and never argues: if the owner says it was missed, it was missed. Fixing is `*fix-issues`. It honours YOLO.
+
+First: `bash .tfcore/utils/tf-phase.sh start log-miss {App}` prints the start time; keep it.
+
+## Steps
+
+1. Sort it. Read the sentence, the checklist row and the documents, then answer the four questions in order and keep the first that fits; ask at most one question, and only when the answer turns on it. In YOLO take the sensible reading and say so in the report.
+   - Did the app's spec say it clearly? No: `--sort spec`. The checklist line is fixed (in this run when it is only the line; through `*amend-docs` when the BRD changes too); the framework is untouched.
+   - Did the framework say it anywhere? No: `--sort unsaid`. The outcome is one line in `TechieFlow-Requirements.md` plus a check, never prose in a task file; name the line in the report for the maintainer.
+   - Was there a check, and did it not catch it? Yes: `--sort weak-check`. The check is fixed; a review becomes a script.
+   - Was it written and ignored anyway? Yes: `--sort ignored`. The rule becomes a hook or script, or is deleted; it never gets more prose.
+2. Classify from the same reading:
+   - The owning row: the row whose scope holds the behaviour. None is a real answer: the defect was never specified.
+   - `--class`: the spec said it and the build did not do it, `missed-requirement` or `partial-implementation`; the spec never said it, `unspecified-gap`; it used to work, `regression`; it works but not as specified, `wrong-behaviour`; `standards-violation`; `spec-contradiction`.
+   - `--why`: which practice let it through: `missing-checklist-item`, `insufficient-verify-method`, `code-audit-limitation`, `ambiguous-acceptance`, `dependency-not-declared`, `instruction-ignored` (a written rule was not honoured; "you were told to" usually means this). Answer it on an owner or production report; leave it out rather than guess otherwise.
+   - `--artifact` (`brd`, `architecture`, `uidesign`, `checklist`, `src`, `tests`, `config`, `devguide`) and `--severity` (`blocker`, `major`, `minor`, by what the owner sees, never by effort).
+3. `bash .tfcore/utils/tf-log-miss.sh {App} --what "<the sentence>" --sort … --req <REQ> --class … --why … --artifact … --severity …` does the rest: the duplicate check (an open miss of the same class is reported, not re-logged, and its empty why or sort is completed), the origin lookup, the record with the sentence and the sort, the readable file, the checklist line (the row demoted to `Needs re-verify` with `⚠ miss <date>: <sentence>`), and the run record. When no row owns it: `--new "<title>" --acceptance "<When … on <screen>, then …>" --section "<screen>"` adds a Not Started row with `BRD-pending`; the report names `*amend-docs` when it is new scope rather than a defect. `--found-by production` for a live report. `--fixed [--fix-run <started>]` when the miss is already repaired: the record is closed at once and the row is left alone; without the run that fixed it, the cost is `none`, never a guess.
+4. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record is the one step 3 wrote; the next command is `*fix-issues {App} <REQ>`.
+5. Report: the block the script printed, the outcome the sort calls for (the checklist line fixed, the requirement line to add, the check to fix, the rule to make mechanical), and a plain sentence when the attribution came out inferred, so the owner knows this miss will not appear in the per-model figures.

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

@@ -72,7 +72,7 @@ If you find yourself wanting to write "overall, across all projects, …" — **
 ### 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.
+- **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 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`.

package/.tfcore/tasks/mockups.md

@@ -1,122 +1,17 @@
 # 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.
+`*mockups {App} [screen|all] [--update]` produces the UI design: `docs/{App}-UIDesign.md`, one section per screen, and one HTML mockup per screen in `docs/mockups/`. The build implements from them; the verifier compares the built screen to them. Called by both day-1 tasks and by `*amend-docs`; `--update` refreshes only new or changed screens and leaves the rest untouched. Never edit source code here.
 
-## Why this exists
+First: `bash .tfcore/utils/tf-phase.sh start mockups {App}` prints the start time and marks the command running.
 
-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.
+## Steps
 
-## 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
+1. `bash .tfcore/utils/tf-mockups-locate.sh` moves any mockup found elsewhere in the repository into `docs/mockups/` and lists what is there.
+2. Read the component reference of the UI library named in the Architecture's Stack decisions (for TrBlazeUI, `.trblazeui/TrBlazeUI-AI-Reference.md`; build once if it is absent). Design only with controls that exist. A control the library lacks is logged as an entry in `docs/{App}-<Library>-Feedback.md`, never designed in silently.
+3. Read the BRD's Screens and flow table: every row is a screen, with its route, roles and fields; a dialog row belongs to its parent screen. A screen that already has a mockup in `docs/mockups/` keeps it and is linked. An app with no screens records "skipped — no UI" in the UIDesign and stops.
+4. For each screen without a mockup (fan out one sub-agent per group of screens when there are many): decide the layout regions, map every region to a control, write `docs/mockups/<screen-slug>.html` with realistic placeholder data in the library's visual language, and fill the screen's section in `docs/{App}-UIDesign.md` from `.tfcore/templates/v4custom/app-uidesign-tmpl.md` (mockup link, roles, regions-to-controls table, fields table, the dialogs it opens, the empty, loading and error states). One shell, one theme, one spacing system across the set.
+5. Make the set click through. The entry screen is the sign-in page (or onboarding, or the home page when there is neither). Every link and every navigation button goes to the mockup it names, written as `<a href="screen.html">` or a form action, never as a script (`onclick="location.href=…"` is refused: it dies in any viewer without scripts): sign in opens the home screen, logout returns to sign in, an "Add" button opens the add screen, a row opens its detail, every menu item leads to its screen. Every screen has a way out. A button that does not navigate shows a message with `onclick`. A dialog opens on its parent page. Sign-in needs no credentials: the button alone navigates.
+6. Anchor every element the build must match with `data-testid`, using the names from the regions-to-controls table: the layout regions, every badge and status indicator, every icon button, every card, table and chart, and every value cell whose width matters. The verifier compares only anchored elements; a mockup without anchors is ungradeable.
+7. `bash .tfcore/utils/tf-doc-check.sh --app {App}`: it refuses a broken link, an unreachable or dead-end screen, an inert button and an unanchored mockup. Fix every FAIL.
+8. When run on its own (not inside a day-1 task), run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"mockups"`.
+9. Report: screens mocked, screens kept, controls used, library gaps logged, and the files written.