@techierathore/techieflow 1.0.2 → 1.0.4

package/.claude/commands/TechieFlow/tasks/facilitate-brainstorming-session.md

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

package/.claude/commands/TechieFlow/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/.claude/commands/TechieFlow/tasks/generate-html.md

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

package/.claude/commands/TechieFlow/tasks/handoff-phase.md

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

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