@techierathore/techieflow 1.0.2 → 1.0.4

package/.claude/commands/TechieFlow/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.

package/.claude/commands/TechieFlow/tasks/refresh-status.md

@@ -1,135 +1,14 @@
 # refresh-status
 
-Rebuild `PROJECT-STATUS.md` from **ground-truth evidence** after a development session was interrupted (lost internet, revoked/changed model access, crashed agent, killed terminal) — i.e. whenever a build/verify phase died BEFORE its mandatory status-update gate (`.tfcore/tasks/_status-update-gate.md`) ran, leaving PROJECT-STATUS stale, wrong, or silent about work that actually happened.
+`*refresh-status {App} [verify]` rebuilds `PROJECT-STATUS.md` from evidence after a session died before its status gate ran: a lost connection, a killed terminal, a crashed agent. It does not trust the status file it finds. Its only writes are PROJECT-STATUS, the checklist's Status, % and Remarks cells where hard evidence contradicts them, and what the status gate writes. It never edits source code and never implements a row.
 
-## Purpose
+First: `bash .tfcore/utils/tf-phase.sh start refresh-status {App}` prints the start time and marks the command running.
 
-The normal flow guarantees PROJECT-STATUS is accurate because every phase ends by writing it. When a phase is killed mid-flight, that guarantee is broken: code may have been written, checklist tables may be half-updated, and PROJECT-STATUS still points at an old "Next command" that no longer matches reality. **This task does NOT trust PROJECT-STATUS.** It reconstructs the true state from the evidence that actually exists in this framework — the checklist Requirements Status tables, what is really in the working tree (the source files and when they were last touched), and a fresh build — then rewrites PROJECT-STATUS to match and tells you the exact next command.
+## Steps
 
-> **No git.** In this framework git is **manual and agent-owned by the human, never by an agent** — no task commits, and nothing here keys off commit history. Ground truth lives in the checklist tables, the files on disk, and the build. (This is a deliberate design rule, mechanically enforced: `.claude/settings.json` DENIES `git`/`gh` and the `.tfcore/hooks/block-git.sh` PreToolUse hook blocks compound forms — see the CLAUDE.md "Hard rules" section.) Do **not** run `git` in this task.
-
-This is a **read-and-reconcile** task. It NEVER edits application source code and NEVER implements requirements. Its only writes are to `PROJECT-STATUS.md`, its `.html`, the checklist Requirements Status tables (Status/%/Remarks cells only, never new files, and only when hard evidence says a cell is wrong), and the BRD's **§4 Development status** table — the derived feature-level snapshot (§4.5), including inserting that section into a legacy BRD that predates it.
-
-## Inputs
-
-- `{AppName}` argument (required; or resolve from `.tfcore/core-config.yaml`).
-- Optional flag `verify` — after reconciling, chain the verifier on any REQ whose true state is ambiguous (see §5). Default is reconcile-only (fast).
-
-## SEQUENTIAL Execution
-
-### 1. Gather ground truth (read-only — run these in parallel)
-
-Collect evidence the interrupted agent could not have faked or selectively updated. Do NOT read PROJECT-STATUS first and reason from it — gather independently, compare last.
-
-1. **Checklist Requirements Status table** (the primary source) — read the top table in the one checklist `docs/{AppName}-Checklist.md` (all REQ prefixes in a single table). This is the per-REQ source of truth (Status / % / Remarks). Terminal statuses: `Verified`, `Done (pre-existing)`, `N/A`. Note `Blocked` rows (library gaps) and especially any row left at `In Progress`/`Implemented` (smoke done, verifier never ran — the classic interruption fingerprint).
-2. **What is actually in the working tree** — look at the source the checklists imply should exist, and *when it was last touched*:
-   - For the REQs the tables claim are done/in-progress, confirm the corresponding components/services/pages actually exist on disk (a row marked `Implemented` whose files are absent is suspect; a row left open whose files DO exist is work that happened but was never recorded).
-   - Compare file modification times against PROJECT-STATUS `last_updated` (read in step 4): **source files newer than `last_updated`** are work that landed *after* the last gate write — the status undercounts it. This is the no-git replacement for "what was committed since the last status write".
-   - Use `ls -lt`, `find . -newer PROJECT-STATUS.md -type f` (scoped to the app's source dirs), Glob/Grep — read-only inspection only. Never modify, stage, or commit anything.
-3. **Fresh build** — run the platform probe and then the invocation ladder at `.tfcore/templates/v4custom/build-invocation-ladder.md`. In OpenCode Docker, standard .NET uses container `dotnet`; a Windows MAUI head uses `winrun`, never direct `cmd.exe`; do not check/install `maui-tizen`. Workload errors `NETSDK1178`/`Microsoft.*.Sdk missing` mean wrong rung, not failure. Record PASS/FAIL and real `CS####` errors only.
-4. **The stale PROJECT-STATUS** — read `PROJECT-STATUS.md` LAST, and only to see what it CLAIMED (`last_updated`, `current_phase`, "Next command"). Treat every field as a hypothesis to confirm or overwrite, never as fact. (Its `last_updated` is also the cutoff you compared file mtimes against in step 2.)
-5. **Library feedback files** — glance at `docs/{AppName}-TrBlazeUI-Feedback.md` / `docs/{AppName}-TechieRag-Feedback.md` for open `Blocked`-causing entries.
-
-### 2. Detect the interruption signature
-
-Decide what really happened by comparing the evidence. Common signatures:
-
-- **Worked-but-unrecorded:** source files newer than PROJECT-STATUS `last_updated`, and/or files exist on disk for REQs the tables still show as open → the work landed but the gate never ran. The checklist tables and/or PROJECT-STATUS undercount progress.
-- **In-flight / partial:** a REQ's expected files only partially exist, or the fresh build errors inside them → a phase was mid-implementation. Those REQs are **In Progress**, NOT done — even if a subagent reported them done before dying.
-- **Smoke-without-verify:** checklist rows at `Implemented`/`In Progress` with no `Verified` → self-smoke ran, verifier was cut off. Those REQs need verification, not rebuilding.
-- **Build regressed:** PROJECT-STATUS says `last_verified_build: PASS` but step 1.3 fails → a later edit broke the build; capture the real `CS####` errors as a Known blocker.
-- **Phase boundary lost:** every row is terminal but PROJECT-STATUS still says `current_phase: Build` → phase actually advanced to `Handoff`; correct it.
-
-State the detected signature in one or two plain sentences. If evidence conflicts (e.g. a table marks a REQ `Implemented` but the build fails on that file), trust the **build + files on disk over the table cell**, and flag the REQ as `PARTIAL`/`FAIL` with a note.
-
-### 3. Reconstruct the true per-REQ picture
-
-For each REQ in the checklist, settle on a status from evidence, in this precedence:
-
-1. **Verifier verdict already in the table** (`Verified`/`FAIL`/`PARTIAL`) → keep, unless step 1.3's build contradicts it.
-2. **`Done (pre-existing)` / `N/A`** → terminal, keep, never touch.
-3. **Implementing files present on disk + build PASS + a smoke/verify Remark present** → `Implemented` (pending verify) at minimum; do not upgrade to `Verified` without a verifier verdict.
-4. **Files absent, partial, or build-broken for that REQ** → `In Progress`; do NOT mark done on a dead subagent's say-so.
-5. **No evidence of any work** → leave as the original open status.
-
-Only write a checklist cell when evidence **contradicts** what's there (e.g. table says `FAIL` but the implementing files are present and the build now passes → set `Implemented` with a dated Remark `recovered by refresh-status: files present + build PASS, pending re-verify`). When in doubt, prefer the *less complete* status — under-claiming triggers a re-verify; over-claiming ships a bug. Never invent `Verified`.
-
-**Reconciling a Status column UP to `Verified`** is allowed in exactly one case: the row's Remarks **already carry a dated verifier verdict** (e.g. `VERIFIED 2026-07-07 …`) that the Status column merely lagged. The PreToolUse hook `.tfcore/hooks/guard-verify.sh` blocks any checklist write introducing `Verified` without a same-day run ledger, so first Write `docs/.last-verify.json` as `{"date":"<today>","app":"{AppName}","mode":"reconcile","evidence":"<the pre-existing verdict date(s) + REQ IDs>"}`, then make the cell edit. Reconcile-mode is ONLY for surfacing a pre-existing verdict — never for promoting smoke results or files-on-disk evidence to `Verified`.
-
-### 4. Rewrite PROJECT-STATUS.md (the whole point)
-
-Overwrite `PROJECT-STATUS.md` to reflect the reconstructed reality, honoring every minimum in `.tfcore/tasks/_status-update-gate.md`.
-
-**Rebuild to the CRISP, FIXED-SHAPE template** (`.tfcore/templates/v4custom/app-project-status-tmpl.md`) — the gate's §"CRISP, FIXED-SHAPE snapshot" applies in full to a reconstruction. Start from the template's section set; do NOT copy forward the old file's per-run dated sections (`## *verify all — formal coverage matrix (…)`, `## *fix-issues — …`, `## *build-phase — …`) or its paragraph-stuffed `current_phase`. If the file you are rebuilding has them, they are the mess this task exists to clean up — drop them, fold any still-true facts into the one-paragraph `## Where I am` + the `## Verification log` table, and keep the result well under ~60 lines. The ONE extra section a reconstruction adds is the `## Recovery note` (item 8) — and only because this was an interrupted-session rebuild. Concretely:
-
-1. `last_updated: {today YYYY-MM-DD}`.
-2. `current_phase` = where the evidence says the project actually is (not what the file claimed).
-3. `last_verified_build` + `last_verified_date` from step 1.3's real build.
-4. **Open requirements** = every non-terminal REQ from the reconciled tables.
-5. **Next command to run** = the exact command that resumes from the true state (Claude Code + OpenCode forms). Examples:
-   - in-flight build work → `/TechieFlow:agents:flow-master *build-phase {AppName}` (OpenCode: `/flow-master *build-phase {AppName}`) (FIX/FRESH mode will re-detect the open REQs from the now-correct table; it calls trblazeui/techierag itself).
-   - smoke-without-verify → `/TechieFlow:agents:verifier *verify ui` (OpenCode: `/flow-verifier *verify ui`) (or `functional`/`all`).
-   - all built, verify open → `/TechieFlow:agents:verifier *verify all` (OpenCode: `/flow-verifier *verify all`).
-6. A **Verification log** row only if a verifier actually ran this session (don't fabricate one); otherwise leave the log untouched.
-7. Library-feedback + standards-compliance lines refreshed only if evidence changed them.
-8. Add a one-block **`## Recovery note ({today})`** section at the end recording: the interruption signature (step 2), which files were found newer-than-status / present-for-open-REQs, which checklist cells were corrected and why, and any REQ now flagged for re-verify. This is the audit trail so the next session — human or AI — knows this status was reconstructed, not gate-written.
-
-Then **re-render** `PROJECT-STATUS.html` via `.tfcore/tasks/generate-html.md` with the shared shell — never hand-rolled HTML. A stale HTML defeats the recovery. Do NOT render the checklists to HTML — they are AI-agent working documents (markdown only); correcting their Requirements Status tables in markdown is sufficient.
-
-### 4.5. Sync the BRD §4 Development status snapshot
-
-Bring `docs/{AppName}-BRD.md`'s **§4 Development status** table in line with the reconciled checklist statuses — it is the human, feature-level view of the same reality you just rebuilt. Use the rollup rule in `.tfcore/tasks/_status-update-gate.md` item 9 (feature → its `Requirements: BRD-…` line → the `REQ-*` those BRDs split into → per-REQ Status; map all-terminal → `Done`, mixed → `Partial`, started-but-unverified → `In progress`, none → `Planned`).
-
-- **If the BRD already has a Development status section:** refresh its rows from the rollup and set `Snapshot as of {today}`.
-- **If the BRD has NO such section** (a BRD authored before this section existed — e.g. AstroLyfe): **insert it now** (one-time migration). Add a `## 4. Development status` H2 immediately after the Scope section, **renumber the following H2 sections by +1**, and **regenerate the BRD's `## Table of Contents`** to match (slug rule = `.tfcore/templates/v4custom/html-render-shell.md §1`). Then fill the table via the rollup. After this run, the status gate keeps it current on every phase.
-- Touch ONLY the §4 table, the heading renumber + TOC the insert requires, and the snapshot date — never requirement text, feature prose, or BRD-N IDs.
-- Re-render `docs/{AppName}-BRD.html` via `.tfcore/tasks/generate-html.md` (shared shell). If you renumbered, double-check every BRD diagram still passes the §5.5 mermaid self-check (you didn't touch them, but the re-render must not introduce bare labels).
-- Note in the §6 report whether §4 was refreshed in place or inserted (migration), and which features changed status.
-
-### 4a. 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":"refresh-status","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.
-
-### 5. Optional verify pass (only if `verify` flag given, or you flagged ambiguity)
-
-If invoked with `verify`, or if step 3 left any REQ in an evidence-ambiguous state (files present but never smoked/verified), chain the verifier: read `.tfcore/tasks/verify-phase.md` and execute it inline with the narrowest scope that covers the ambiguous REQs (`ui` / `functional` / `all` / explicit REQ-ID list) — skip its §0 question, scope is known. The verifier writes verdicts into the tables; then re-run step 4's PROJECT-STATUS write so it reflects the fresh verdicts. The verifier never edits source, so this stays safe to run during recovery.
-
-### 6. Report to the user
-
-Print a tight recovery summary (this is for a human who just lost their session):
-- **What happened:** the interruption signature in one line.
-- **What was recovered:** worked-but-unrecorded REQs, in-flight REQs, build state.
-- **What PROJECT-STATUS now says:** current_phase + open-REQ count.
-- **Exact next command** to resume (copy-paste, both harness forms).
-- **Anything needing a human decision** (e.g. half-finished edits to review, or work the human may want to commit manually before resuming — committing is the human's job, never this task's).
-
-## Guardrails
-
-- NEVER run `git` (or `gh`). Git is manual in this framework; this task reconstructs status from checklist tables + working-tree files + build only.
-- NEVER edit application source code, requirement text, feature prose, BRD-N IDs, or Architecture content. The ONLY BRD edit permitted is maintaining the **§4 Development status** table — a derived snapshot — plus, for a legacy BRD lacking it, inserting that one section with the heading-renumber + TOC regen described in §4.5. Everything else in the BRD is read-only.
-- NEVER mark a REQ `Verified` without an actual verifier verdict produced this session or already present in the table.
-- NEVER create dated `docs/qa/*.md` / `docs/verify/*.md` files. The checklist tables + PROJECT-STATUS are the only status surfaces.
-- Prefer under-claiming to over-claiming when evidence is thin — a needless re-verify is cheap; a falsely-"done" bug is not.
-- This task is itself a checklist-executing task: it ends by leaving PROJECT-STATUS accurate. Do not hand back before §4 is written.
-
-## Output Checklist
-
-- [ ] Ground truth gathered independently (checklist tables, working-tree files + mtimes, fresh build) BEFORE reading PROJECT-STATUS — and WITHOUT git
-- [ ] Interruption signature stated
-- [ ] Per-REQ statuses reconciled from evidence (no fabricated `Verified`)
-- [ ] `PROJECT-STATUS.md` overwritten to true state with a dated `## Recovery note`
-- [ ] BRD §4 Development status table refreshed from the reconciled checklists (or inserted + headings renumbered + TOC regenerated, for a legacy BRD that lacked it) — §4 table only, no requirement text touched
-- [ ] `PROJECT-STATUS.html` and `docs/{AppName}-BRD.html` re-rendered (checklists are NOT rendered to HTML — markdown only)
-- [ ] Optional verify pass run if requested / ambiguity remained
-- [ ] User given the exact copy-paste next command
+1. `bash .tfcore/utils/tf-status-evidence.sh {App}` prints what the stale status file claims, the files under `src/` and `tests/` changed after it was written, the checklist rows left at `Implemented`, `In Progress`, `Needs re-verify`, `PARTIAL` or `FAIL`, and the build verdict. Read the files it names before you believe any cell: a row marked done whose files are absent is not done; a row left open whose files exist and build is work that happened and was never recorded.
+2. Say in one or two sentences what happened. The usual shapes: work landed but the gate never ran (files newer than the status, rows undercount); a row was mid-implementation (its files partial, or the build fails inside them); smoke ran and the verifier was cut off (rows at `Implemented` with no `Verified`); the build regressed after the last gate; every row is terminal but the phase still says Build.
+3. Settle each open row from evidence, in this order: a verifier verdict already in the table stays unless the build contradicts it; `Done (pre-existing)` and `N/A` stay; files present, build passing and a dated smoke or verify Remark mean `Implemented`; files absent, partial or build-broken mean `In Progress`; no evidence means the row keeps its status. Change a cell only when evidence contradicts it, with a dated Remark `recovered by refresh-status: <why>`. When in doubt, under-claim: a needless re-verify is cheap, a false done ships a bug. Never write `Verified` from files or a smoke; the only allowed promotion to `Verified` is a row whose Remarks already carry a dated verifier verdict the Status column lagged, and then `docs/.last-verify.json` is written first as `{"date":"<today>","app":"{App}","mode":"reconcile","evidence":"<the verdict dates and row ids>"}` so the guard accepts it.
+4. With `verify`, or when a row's state is still ambiguous after step 3 (files present, never smoked or verified), execute `.tfcore/tasks/verify-phase.md` inline with the narrowest scope that covers those rows; it writes the verdicts.
+5. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"refresh-status"`. PROJECT-STATUS gets one extra section, `## Recovery note ({today})`: the shape of the interruption from step 2, the files found newer than the status, the cells corrected and why, and the rows flagged for re-verify. The next command is the one the facts script printed.
+6. Report, for a person who just lost a session: what happened in one line, what was recovered, what the status now says, the exact next command in both harness forms, and anything only a person can decide.

package/.claude/commands/TechieFlow/tasks/split-brd.md

@@ -1,131 +1,15 @@
 # split-brd
 
-Split the BRD into the single AI-targeted requirement doc: the app Checklist (`docs/{AppName}-Checklist.md`).
+Turns the BRD ledger into the one checklist, `docs/{App}-Checklist.md`. The prefix of a row routes its work: `REQ-UI-` to the UI sub-agent from the mockups, `REQ-RAG-` to the RAG sub-agent, `REQ-FN-` and `REQ-NFR-` to the build phase. Called by both day-1 tasks; the owner never types it. Never edit source code here.
 
-## Purpose
+First: `bash .tfcore/utils/tf-phase.sh start split-brd {App}` prints the start time and marks the command running.
 
-The BRD captures business intent with `BRD-N` IDs. Implementation needs finer-grained, type-tagged requirements. There is **one checklist per app**; the requirement *type* is carried by the REQ prefix, which routes work to the right builder:
-- `REQ-UI-*` → built by `/trblazeui` (from the approved mockups), invoked as a sub-agent by the unified `build-phase`
-- `REQ-RAG-*` → built by `/techierag`, invoked as a sub-agent by `build-phase`
-- `REQ-FN-*` / `REQ-NFR-*` → built directly by `build-phase` (flow-master)
+## Steps
 
-This task converts each `BRD-N` into one or more `REQ-*` items inside the one checklist.
-
-## Inputs
-
-- `{AppName}` argument (required; or resolve from core-config.yaml).
-
-## SEQUENTIAL Execution
-
-### 1. Load inputs
-
-- `docs/{AppName}-BRD.md` — must exist. Parse `BRD-N` IDs and their text.
-- `docs/{AppName}-Architecture.md` — read for module boundaries and stack.
-- `docs/{AppName}-UIDesign.md` + `docs/mockups/*.html` — if they exist (greenfield, post-`*mockups`), read them so each `REQ-UI-*` cites the mockup screen it realizes.
-
-### 2. Classify each BRD-N
-
-For each `BRD-N`, classify as UI / FN / RAG / NFR:
-- **UI**: any user-visible change — page, component, form, dashboard, layout.
-- **RAG**: anything involving LLM, embedding, vector search, chat, prompt templates, token tracking, tool calling.
-- **NFR**: performance, security, accessibility, observability, compliance.
-- **FN**: everything else — backend logic, data, APIs, integrations, business rules.
-
-A single `BRD-N` may map to multiple REQs (e.g. a "settings page that saves to DB" splits into REQ-UI-N (the page) and REQ-FN-N (the save handler)).
-
-### 2.5. Dev-plan seeding (CONDITIONAL — brownfield projects with an existing plan)
-
-Check `docs/` for an existing development/phase plan (`*Development-Plan*.md`, `*Dev-Plan*.md`, `*Implementation-Plan*.md`, `*Roadmap*.md`, or any doc structured as Phase 0/1/2… with build order/statuses). If one exists:
-
-- Carry its phase structure into §3 — tag each REQ with its phase (e.g. `(BRD-21, Phase 1)`) and order rows by phase.
-- **Preserve every column the plan tracked** — the Requirements Status table must be a SUPERSET of the plan's, never a lossy summary. For each migrated REQ fill Status, **%**, **Remarks**, Details: carry the plan's `% Done` verbatim and its full dated status remark (e.g. "Completed 2026-04-30 (DTOs split…)") into Remarks — do not truncate.
-- COMPLETE/done/shipped → Status `Done (pre-existing)`, `%` = plan's figure (usually `100%`), Remarks = plan's note + `per {plan-file} §{section}`. Build agents must NOT rebuild these. Partial → `In Progress`/`PARTIAL` with the plan's `%`+remark. Not started → `Not Started`, `0%`.
-- Add a header note to the checklist: `> Migrated from {plan-file} on {YYYY-MM-DD}. Phase structure, completion %, and status remarks carried over verbatim — verify before building.`
-- Do not modify the plan file's content. After migration it is superseded — move it unchanged to `docs/OldDocs/` (create the folder if missing; date-suffix on name collision) and note this in the §6 summary.
-
-If no plan exists, skip — classify purely from the BRD.
-
-### 3. Write `docs/{AppName}-Checklist.md`
-
-Schema per `.tfcore/templates/v4custom/app-checklist-tmpl.md` — the **Requirements Status** table sits at the TOP (single source of truth for the WHOLE app), with all REQ classes in one table, and the per-REQ detail follows in prefix-grouped sections with `<a id="d-REQ-ID">` anchors the Details column links to:
-```markdown
-# {AppName} — Checklist
-
-## Goal
-{one paragraph; ties back to BRD §1}
-
-## Requirements Status
-| ID | Requirement | Status | % | Remarks | Details |
-|----|-------------|--------|---|---------|---------|
-| REQ-UI-001  | {short name} | Not Started | 0% | — | [view](#d-req-ui-001) |
-| REQ-FN-001  | {short name} | Not Started | 0% | — | [view](#d-req-fn-001) |
-| REQ-RAG-001 | {short name} | Not Started | 0% | — | [view](#d-req-rag-001) |
-| REQ-NFR-001 | {short name} | Not Started | 0% | — | [view](#d-req-nfr-001) |
-{Status values + % guide + Remarks note — copy the legend from the template}
-
-## UI / Pages
-### Page: {page name} (`{route}`)
-<a id="d-req-ui-001"></a>
-- **REQ-UI-001** — {description; traces to BRD-X}. *Mockup:* docs/mockups/{screen}.html (if mockups exist).
-  - *Acceptance:* {specific testable criterion}; controls do not overlap at desktop + mobile widths (visual gate).
-
-## Functional requirements
-<a id="d-req-fn-001"></a>
-- **REQ-FN-001** — {trigger / acceptance} (BRD-X)
-
-<!-- If the source BRD NFR carried a `perf-budget:` line, copy it into the REQ's Acceptance
-     bullet VERBATIM — same grammar, same numbers. verify-phase §4c reads it literally and
-     grades speed only where it exists. Never synthesize one for an NFR that lacked it, and
-     never drop one that was there: both silently change what "Verified" means for that REQ. -->
-
-
-## RAG / AI requirements (→ /techierag)
-<a id="d-req-rag-001"></a>
-- **REQ-RAG-001** — {trigger / acceptance via TechieRag} (BRD-X)
-
-## Non-functional
-<a id="d-req-nfr-001"></a>
-- **REQ-NFR-001** — {perf/security/accessibility} (BRD-X)
-```
-
-Cross-link: every REQ-N's description ends with `(BRD-X)` so traceability is two-way.
-
-### 4. Trace check
-
-- Every `BRD-N` should appear at least once in the checklist's Requirements Status table.
-- If any `BRD-N` is unmapped, list it in the output summary and ask: "BRD-X has no REQ. Is it deferred, or should I map it now?"
-
-### 5. Output summary
-
-Report counts:
-- `K` `REQ-UI-*`, `M` `REQ-FN-*`, `N` `REQ-RAG-*`, `P` `REQ-NFR-*` items in the checklist
-- Any unmapped `BRD-N`s flagged in §4
-
-Update `PROJECT-STATUS.md` per `.tfcore/tasks/_status-update-gate.md` (this task counts as a phase — the gate applies):
-- Next phase is always the unified build while any REQ is open: current_phase `Build`, Next command `/TechieFlow:agents:flow-master *build-phase {AppName}` (OpenCode: `/flow-master *build-phase {AppName}`). `build-phase` clusters all open REQs and calls `/trblazeui` (REQ-UI-*, from the mockups) and `/techierag` (REQ-RAG-*) as sub-agents itself — you do NOT point the user at a separate UI or RAG command.
-- `last_updated`: today. Leave `last_verified_build`/`last_verified_date` as-is (no build this phase).
-- Sync "Open requirements" to the new Status table (everything non-terminal).
-- Append a row to "Verification log" — N/A (no verify yet)
-- List unmapped open requirements if any
-- Re-render `PROJECT-STATUS.html` (gate minimum #8). Do NOT render the checklist to HTML — it is an AI-agent working document (markdown only).
-
-### 6. 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":"split-brd","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.
-
-## Output Checklist
-
-- [ ] `docs/{AppName}-Checklist.md` exists with REQ-UI/FN/RAG/NFR-* IDs each back-linking to BRD-N, in one Requirements Status table
-- [ ] Every `BRD-N` is mapped or explicitly deferred
-- [ ] `PROJECT-STATUS.md` updated with `Build` phase + `*build-phase` next command (+ re-rendered HTML)
+1. `bash .tfcore/utils/tf-split-brd.sh {App}` writes the checklist draft from `docs/{App}-BRD.md`: one row per BRD item in the template shape, one section per screen, acceptance and perf-budget lines copied verbatim, the class guessed. An item with no acceptance line gets a TODO line that the checker refuses. On a re-run use `--force`; `*amend-docs` uses `--add-missing`. A Large project has one checklist per phase: `--all-phases` writes them all from `docs/{App}-Phases.md`; without a flag the script takes the phase from `appPhase` in `core-config.yaml`.
+2. Read the draft and correct the class where the guess is wrong: UI is anything a user sees on a screen; RAG is anything with a model, embeddings, vectors, prompts or chat; NFR is speed, security, accessibility, observability or compliance; FN is everything else. Split a BRD item into two rows when it holds both a screen and a rule (a settings page and the save that persists it). Renumber only the rows you changed, within their prefix.
+3. Fill every TODO acceptance line in the form "When <actor> <does what> on <screen>, then <observable result>"; an NFR row names the measurement instead of a screen.
+4. If a phased plan is among the harvested documents (a file named like a development plan or roadmap, or content in phases with statuses), carry it in: tag each row with its phase, copy the plan's percentage and remark verbatim into the row, mark completed items `Done (pre-existing)` with the plan reference in Remarks, and add the note "> Migrated from {plan-file} on {date}" under the Goal. Then move the plan to `docs/OldDocs/` with `bash .tfcore/utils/tf-day1-files.sh --archive <file>`.
+5. `bash .tfcore/utils/tf-doc-check.sh --app {App}`: it refuses a BRD item without a row, a row without its acceptance line, a UI row without its mockup and a duplicate id. Fix every FAIL.
+6. When run on its own (not inside a day-1 task), run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"split-brd"`; the next command is `*build-phase {App}`.
+7. Report the row counts per prefix and any class you changed.

package/.claude/commands/TechieFlow/tasks/triage-and-fix.md

@@ -0,0 +1,14 @@
+# triage-and-fix
+
+`*triage-and-fix {App} {evidence}` runs the owner's whole bug sequence in one go, in YOLO: compare every screen to its mockup, triage the reported bugs, log every root cause with its discovery cost, fix, log every fix with its cost, refresh the metrics, and end with one summary per step. The separate commands stay for when only one of them is wanted. Evidence is a folder of screenshots with an optional notes file, a written list, or nothing (then the screens comparison is the evidence).
+
+First: `bash .tfcore/utils/tf-phase.sh start triage-and-fix {App}` prints the start time; keep it. `bash .tfcore/utils/tf-yolo.sh on --source triage-and-fix` unless YOLO is already on.
+
+## Steps
+
+1. Compare. `bash .tfcore/utils/tf-verify-list.sh {App} all`, `tf-verify-boot.sh start`, then `tf-verify-screens.sh --list … --base <url>` and `tf-mockup-parity.sh --base <url> --screen … --json-out tests/.artifacts/verify/parity.json` over every screen. Every screen that renders empty, looks broken or drifts from its mockup is an issue, added to the owner's evidence with its screenshot.
+2. Triage. `.tfcore/tasks/triage-issues.md` steps 3 and 4 on the combined issue list, then `tf-triage.sh {App} close --started <the step-0 time> --cmd fix-issues`.
+3. Fix. `.tfcore/tasks/fix-issues.md` steps 2 to 5 on the demoted rows (the builders, the build, the smoke, the verify, `tf-fix-close.sh`).
+4. Metrics. Execute `.tfcore/tasks/metrics-report.md`.
+5. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"triage-and-fix"` and the rows touched. When this run is the last step of a goal, write the sentinel (`.tfcore/tasks/_yolo-mode.md`).
+6. Summary, one short section per step: screens compared and what the comparison found; root causes found and logged, each with its miss id and discovery cost; fixes made and logged, each with its verdict and fix cost; rows re-verified by status; metrics refreshed, the report's path; the next command from the gate.