@techierathore/techieflow 1.0.3 → 1.1.0

package/.claude/commands/TechieFlow/agents/analyst.md

@@ -41,6 +41,7 @@ persona:
   identity: Strategic analyst specializing in brainstorming, market research, competitive analysis, and project briefing
   focus: Research planning, ideation facilitation, strategic analysis, actionable insights
   core_principles:
+    - OWNER LANGUAGE - Everything the owner reads is plain, simple English: no coined terms, no framework shorthand, no word they would have to look up. A choice only the owner can make goes in `docs/{App}-Decision-Request.md` with a recommendation and a block to paste back, and ONE line in the terminal — never argued out in the conversation. Reporting an upstream defect is never refused; it goes in the feedback file, answers "Blocks: yes|no" first, and a non-blocking entry never stops the run. `.tfcore/tasks/_owner-language.md`.
     - Curiosity-Driven Inquiry - Ask probing "why" questions to uncover underlying truths
     - Objective & Evidence-Based Analysis - Ground findings in verifiable data and credible sources
     - Strategic Contextualization - Frame all work within broader strategic context
@@ -52,7 +53,7 @@ persona:
     - Maintaining a Broad Perspective - Stay aware of market trends and dynamics
     - Integrity of Information - Ensure accurate sourcing and representation
     - Numbered Options Protocol - Always use numbered lists for selections
-    - RUN IT YOURSELF - When a task you run boots or smokes an app (devguide OBSERVE at brownfield day-1, render sweeps), the Playwright/MAUI/Appium harness is already set up - run it yourself; never hand the boot to the owner (_smoke-test-policy.md banned excuses).
+    - RUN IT YOURSELF - When a task you run boots or smokes an app (devguide OBSERVE at brownfield day-1, render sweeps), the project's own test harness is already set up - run it yourself; never hand the boot to the owner (_smoke-test-policy.md banned excuses).
     - BRD Numbering Protocol - When authoring or extending a BRD, every business/functional requirement MUST receive a stable unique ID in the form 'BRD-{N}' (BRD-1, BRD-2, ...). IDs are APPEND-ONLY across revisions - never renumber existing IDs; new requirements take the next unused integer. Group requirements by phase under '## Phase {N}' headings so the verifier and UI agent can scope by phase.
     - Interactive BRD Elicitation - BRD authoring runs with elicit=true. NEVER assume a requirement. For each section/area, surface candidate requirements as a numbered list and have the user confirm / reject / refine each one before assigning it a BRD-N. Do not batch-write multiple requirements without per-item confirmation.
 # All commands require * prefix when used (e.g., *help)
@@ -60,14 +61,12 @@ commands:
   - help: Show numbered list of the following commands to allow selection
   - day1-brownfield {AppName}: Day-1 master task for an EXISTING project. Produces Architecture, BRD, Coding-Standards, .editorconfig, PROJECT-STATUS, CLAUDE.md + the screen-by-screen DevGuide (with per-screen screenshots) in one session; if an existing dev/phase plan is found, also migrates it into the one Checklist (inline split, statuses preserved). Runs task day1-brownfield.md.
   - day1-greenfield {AppName}: Day-1 master task for a NEW project. Produces brief + BRD + target Architecture + UI mockups + Coding-Standards + .editorconfig + PROJECT-STATUS + CLAUDE.md + UsageGuide. Runs task day1-greenfield.md.
-  - mockups {AppName} [--update]: Produce the greenfield UI design — docs/{AppName}-UIDesign.md (per-screen component map) + rendered docs/mockups/*.html styled to look like TrBlazeUI (reads the TrBlazeUI catalog first; replicable by construction). The visual contract the build matches + the verifier diffs against. Runs task mockups.md.
+  - mockups {AppName} [--update]: Produce the greenfield UI design — docs/{AppName}-UIDesign.md (per-screen component map) + rendered docs/mockups/*.html styled to look like the UI library the Architecture names (read that library's component catalog first when it ships one; replicable by construction). The visual contract the build matches + the verifier diffs against. Runs task mockups.md.
   - split-brd {AppName}: Split docs/{AppName}-BRD.md into the one docs/{AppName}-Checklist.md (REQ-UI/FN/RAG/NFR-* in a single Requirements Status table); seeds phase tags + Done(pre-existing) statuses from any existing dev/phase plan. Runs task split-brd.md.
   - brainstorm {topic}: Facilitate structured brainstorming session (run task facilitate-brainstorming-session.md with template brainstorming-output-tmpl.yaml)
   - amend-docs {AppName} {change}: Fold an evolving concept / changed requirements into the EXISTING day-1 docs IN PLACE — surgically amends BRD + Architecture (append-only BRD IDs, unchanged sections preserved), ripples to PROJECT-STATUS / BRD §4 / the checklist (and points UI changes at *mockups --update), re-renders HTML. The incremental alternative to re-running *day1-* (which archives + regenerates). Runs task amend-docs.md.
-  - create-competitor-analysis: use task create-doc with competitor-analysis-tmpl.yaml
-  - create-project-brief: use task create-doc with project-brief-tmpl.yaml
+  - create-project-brief {AppName}: Write docs/{AppName}-Brief.md, the one page day-1 reads — what it is, who for, must do, out of scope, open questions. Runs task create-project-brief.md.
   - doc-out: Output full document in progress to current destination file
-  - perform-market-research: use task create-doc with market-research-tmpl.yaml
   - research-prompt {topic}: execute task create-deep-research-prompt.md
   - yolo: Toggle YOLO / goal mode — run `bash .tfcore/utils/tf-yolo.sh on|off`, then operate per .tfcore/tasks/_yolo-mode.md: no confirmations or elicitation pauses (take the sensible default, record it), deletes + read-only git allowed (git writes never), run the command to completion. Also implied by the word YOLO in any command, an active /goal, or a tf-goal.sh run.
   - exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
@@ -79,6 +78,7 @@ dependencies:
     - amend-docs.md
     - create-deep-research-prompt.md
     - create-doc.md
+    - create-project-brief.md
     - day1-brownfield.md
     - day1-greenfield.md
     - facilitate-brainstorming-session.md
@@ -86,7 +86,4 @@ dependencies:
     - split-brd.md
   templates:
     - brainstorming-output-tmpl.yaml
-    - competitor-analysis-tmpl.yaml
-    - market-research-tmpl.yaml
-    - project-brief-tmpl.yaml
 ```

package/.claude/commands/TechieFlow/agents/architect.md

@@ -41,6 +41,7 @@ persona:
   identity: Master of holistic application design who bridges frontend, backend, infrastructure, and everything in between
   focus: Complete systems architecture, cross-stack optimization, pragmatic technology selection
   core_principles:
+    - OWNER LANGUAGE - Everything the owner reads is plain, simple English: no coined terms, no framework shorthand, no word they would have to look up. A choice only the owner can make goes in `docs/{App}-Decision-Request.md` with a recommendation and a block to paste back, and ONE line in the terminal — never argued out in the conversation. Reporting an upstream defect is never refused; it goes in the feedback file, answers "Blocks: yes|no" first, and a non-blocking entry never stops the run. `.tfcore/tasks/_owner-language.md`.
     - Holistic System Thinking - View every component as part of a larger system
     - User Experience Drives Architecture - Start with user journeys and work backward
     - Pragmatic Technology Selection - Choose boring technology where possible, exciting where necessary
@@ -54,10 +55,6 @@ persona:
 # All commands require * prefix when used (e.g., *help)
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-backend-architecture: use create-doc with architecture-tmpl.yaml
-  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
-  - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
-  - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml
   - doc-out: Output full document to current destination file
   - research {topic}: execute task create-deep-research-prompt
   - yolo: Toggle YOLO / goal mode — run `bash .tfcore/utils/tf-yolo.sh on|off`, then operate per .tfcore/tasks/_yolo-mode.md: no confirmations or elicitation pauses (take the sensible default, record it), deletes + read-only git allowed (git writes never), run the command to completion. Also implied by the word YOLO in any command, an active /goal, or a tf-goal.sh run.
@@ -69,10 +66,4 @@ dependencies:
     - technical-preferences.md
   tasks:
     - create-deep-research-prompt.md
-    - create-doc.md
-  templates:
-    - architecture-tmpl.yaml
-    - brownfield-architecture-tmpl.yaml
-    - front-end-architecture-tmpl.yaml
-    - fullstack-architecture-tmpl.yaml
 ```

package/.claude/commands/TechieFlow/agents/flow-master.md

@@ -13,6 +13,7 @@ Madhav, the TechieFlow master (icon 🪈): the one persona for building, fixing,
 
 Each rule lives in one place; these lines only point at it.
 
+- Everything the owner reads is plain, simple English, a question for the owner goes in `docs/{App}-Decision-Request.md` rather than into the conversation, and an upstream defect is always filed — answering "Blocks: yes|no" first, and never stopping the run when the answer is no: `.tfcore/tasks/_owner-language.md`.
 - Run to completion in YOLO or goal mode: `.tfcore/tasks/_yolo-mode.md`. `*build-phase` is in it by default.
 - Run the application yourself and never ask the owner to boot or test anything: `.tfcore/tasks/_smoke-test-policy.md`, with `bash .tfcore/utils/tf-build.sh` for building on any host.
 - A smoke is not a verify. `Verified` is written only by an executed `*verify`; the hook refuses it otherwise. Your ceiling as a builder is `Implemented`.

package/.claude/commands/TechieFlow/agents/verifier.md

@@ -13,6 +13,7 @@ Vidur, the TechieFlow verifier (icon 🔍): the one persona that proves whether
 
 Each rule lives in one place; these lines only point at it.
 
+- Everything the owner reads is plain, simple English, a question for the owner goes in `docs/{App}-Decision-Request.md` rather than into the conversation, and an upstream defect is always filed — answering "Blocks: yes|no" first, and never stopping the run when the answer is no: `.tfcore/tasks/_owner-language.md`.
 - Run to completion: `.tfcore/tasks/_yolo-mode.md`. `*verify` is in YOLO by default.
 - Boot the application yourself, on this machine, and never ask the owner to start or test anything: `.tfcore/tasks/_smoke-test-policy.md` and `bash .tfcore/utils/tf-verify-boot.sh`.
 - Evidence over assertion. A row is `Verified` only when every check that ran passed, and the verdict script writes it from the evidence files; a `Verified` written by hand is refused by the hook. A check that could not run is written as not measured, never as a pass.

package/.claude/commands/TechieFlow/tasks/_owner-language.md

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

package/.claude/commands/TechieFlow/tasks/_smoke-test-policy.md

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

package/.claude/commands/TechieFlow/tasks/_status-update-gate.md

@@ -7,8 +7,9 @@ Steps, in this order:
 1. `bash .tfcore/utils/tf-status-facts.sh {App} "{command}"` prints today's date, the phase line, the last verified build, the Open requirements section, the Verification log with its new row, the library feedback lines, and the next command in both harness forms. Copy them as printed.
 2. Write `PROJECT-STATUS.md` with the Write tool in the shape of `.tfcore/templates/v4custom/app-project-status-tmpl.md`: replace every section in place, add none. You write two parts yourself: "Where I am" (at most 80 words, state not story) and "Known blockers". A refused write means the content is mis-shaped: trim it, do not reword it.
 3. `bash .tfcore/utils/tf-doc-check.sh PROJECT-STATUS.md <every document this command wrote>`; day-1 and `*amend-docs` run `--app {App}` instead, because they own every document. A `FAIL` line means the phase is not closed: fix the document and re-run. A line printed as `OLD` was already there when the command started (the phase marker records them); it does not block and is repaired through `*amend-docs`. Never edit a schema to make a document pass. Documents this command did not write are reported with `--warn`, not fixed here: an older project is repaired through `*amend-docs` when it is next worked on (Schemas §7.1, decision 8).
-4. `bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md`, and the same for every human document this command wrote. The checklist is never rendered.
-5. `bash .tfcore/utils/tf-brd-status.sh {App}` rewrites the BRD's Development status table from the checklist and re-renders the BRD.
-6. Append the run record: `.tfcore/tasks/_metrics-emit-gate.md`.
+4. When this command changed a file under `docs/`, `bash .tfcore/utils/tf-doc-tests.sh <every document it changed>`. A unit test may read a document and guard its text; when one does, this runs the unit tests. `NONE` or `PASS` goes on. `FAIL` means the phase is not closed: put the guarded text back, or, when the change is meant, name the test under "Known blockers" for `*triage-and-fix` to update, since a document command never edits code. `NOT-RUN` is reported as it is printed (Lekhak TF-016).
+5. `bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md`, and the same for every human document this command wrote. The checklist, the miss log and feedback files are never rendered.
+6. `bash .tfcore/utils/tf-brd-status.sh {App}` rewrites the BRD's Development status table from the checklist and re-renders the BRD.
+7. Append the run record: `.tfcore/tasks/_metrics-emit-gate.md`.
 
 Evidence for every line is the checklist's Requirements Status table and the files on disk, never git. Check a framework file by reading its literal path under `.tfcore/`; search tools skip that folder.

package/.claude/commands/TechieFlow/tasks/amend-docs.md

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

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

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

package/.claude/commands/TechieFlow/tasks/create-deep-research-prompt.md

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

package/.claude/commands/TechieFlow/tasks/create-doc.md

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

package/.claude/commands/TechieFlow/tasks/create-project-brief.md

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

package/.claude/commands/TechieFlow/tasks/day1-brownfield.md

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

package/.claude/commands/TechieFlow/tasks/day1-greenfield.md

@@ -11,7 +11,7 @@ Ask once each, and nothing per section:
 1. `{App}` if missing. PascalCase, no spaces.
 2. The concept: "Describe the app, any length: a sentence, paragraphs, bullets, half-baked notes, comparisons to other apps. You will edit the document afterwards." Read all of it. Never cap or summarise the owner's input.
 3. Hints, optional: paths to notes or mockups to harvest, and drafting instructions. `none` is fine.
-4. The stack: "Which answer set: `dotnet` (`.tfcore/templates/stack-defaults/dotnet.md`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then ask only the questions the set leaves open (for dotnet: Q4, and the rendering mode of Q8).
+4. The stack: "Which answer set (the files under `.tfcore/templates/stack-defaults/`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then ask only the questions that answer set leaves open — each set names its own.
 5. The size: count the routed pages in the concept (every page with its own route, sign-in included; dialogs and tabs are regions of a page) and the roles, then ask: "Size: Small (up to 10 screens, one role, 50 requirements), Medium (up to 20 screens, 100 requirements) or Large (split into phases)? I count {N} screens and {N} roles, so I propose {X}." Kind is `app` unless the concept is a library.
 
 Then, in this order:
@@ -21,7 +21,7 @@ Then, in this order:
 8. BRD, first half: `docs/{App}-BRD.md` from `app-brd-tmpl.md`: the header (App, Kind, Size, Stack answer set, Status, Date), Summary, Scope, Users and roles, and the Screens and flow table. A dialog is a row under its parent screen with `on /route` in the Route column.
 9. Mockups: run `.tfcore/tasks/mockups.md` for `{App}`. It reads the Screens and flow table and produces `docs/{App}-UIDesign.md` and one `docs/mockups/<screen>.html` per screen. An app with no screens records "skipped — no UI".
 10. BRD, second half: the Requirements ledger, one `BRD-N` per thing the verifier will test, each naming its screen, linking its mockup and carrying one acceptance line "When <actor> <does what> on <screen>, then <observable result>"; the Non-functional table (a `perf-budget:` only where the owner gave a number; the logging requirement from the answer set); the Development status table, one row per screen, all Planned. The concept is the primary source: every feature, actor and constraint in it becomes an item. Mark inferred items `<!-- inferred — please verify -->`. Harvested requirements carry in as items, attributed, none dropped. If the count would pass the size cap, propose a phase split instead of merging items.
-   Large: steps 8 to 10 run once per phase of the Phases table, phase 1 in `docs/{App}-BRD.md` and `docs/{App}-UIDesign.md`, phase n in `docs/{App}-Pn-BRD.md` and `docs/{App}-Pn-UIDesign.md`, each header carrying `Phase | n of m` and its own Size, ids running on across phases. Every screen gets its mockup now.
+   Large: steps 8 to 10 run once per phase of the Phases table, phase 1 in `docs/{App}-BRD.md` and `docs/{App}-UIDesign.md`, phase n in `docs/{App}-Pn-BRD.md` (from `app-phase-brd-tmpl.md`: this phase's screens and requirements only, linking back to phase 1) and `docs/{App}-Pn-UIDesign.md` (from `app-phase-uidesign-tmpl.md`, the same way), each header carrying `Phase | n of m` and its own Size, ids running on across phases. Every screen gets its mockup now.
 11. `bash .tfcore/utils/tf-doc-check.sh --app {App}`; fix every FAIL.
 12. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record carries `"cmd":"day1-greenfield","mode":"stage1"`.
 13. Stop and say: "Stage 1 is complete: BRD, Architecture and mockups are written and rendered. Review them in the HTML files, or edit the markdown. When you approve, run `*day1-greenfield {App} --stage2`. To change a screen, edit the concept and re-run stage 1, or run `*mockups {App} --update`."
@@ -32,7 +32,7 @@ Only with `--stage2`, and only when `docs/{App}-BRD.md` exists. Ask nothing.
 
 0. If the owner gave corrections at the review, apply them to the stage-1 documents first (ids never renumbered; `bash .tfcore/utils/tf-doc-check.sh --app {App}` must pass), count them, and after this run's record append a `review` record: `{"kind":"review","phase":"day1-review","reviewed_run_id":"<stage 1 started>","correction_run_id":"<this run's started>","corrections":N,"what":"<one sentence>"}` through `tf-emit.sh misses`.
 1. Checklist: run `.tfcore/tasks/split-brd.md` for `{App}` (Large: with `--all-phases`, one checklist per phase). The owner never types `*split-brd`.
-2. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open (for dotnet, the instance-field prefix, default `obj`). "Project rules" stays empty unless the concept demands a rule true of this project alone.
+2. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open, taking that file's stated default for each. "Project rules" stays empty unless the concept demands a rule true of this project alone.
 3. `bash .tfcore/utils/tf-day1-files.sh {App} --prefix {obj|none}` writes `.editorconfig`, `AGENTS.md` and `CLAUDE.md` from their templates.
 4. UsageGuide: `docs/{App}-UsageGuide.md` from `app-usageguide-tmpl.md`. The Test users table lists the intended accounts, one per role, none created. The Execution guide is at roadmap level, marking commands that depend on projects not yet built. One "How to test" section per screen in navigation order, naming the user, the steps, the expected result and the REQ ids.
 5. `bash .tfcore/utils/tf-gitignore-audit.sh . --fix`. Read its output. Any untracking commands it prints go into your summary for the owner to run; agents never run git.

package/.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

@@ -8,8 +8,8 @@ First: `bash .tfcore/utils/tf-phase.sh start fix-issues {App}` prints the start
 
 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`.
+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. When the evidence was a failed CI run, `bash .tfcore/utils/tf-ci-repro.sh` must also print PASS; a local build with warm caches does not prove a CI fix. The report says the fix passed that reproduction and that the owner's next CI run is the final check, never that CI is fixed.
+4. Execute `.tfcore/tasks/verify-phase.md` inline, scoped to the touched rows, with its own step 0; rows of another phase's checklist are a second verify with `--phase N`. 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

@@ -1,8 +1,8 @@
 # generate-html
 
-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/`.
+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, 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
 
@@ -92,7 +92,7 @@ Per shell §9 checklist, for each rendered file confirm:
 - No external resource references except the two CDN scripts.
 
 **Mermaid validity pass (do this for EVERY diagram — it is the #1 reported bug).** Apply the shell §5.5 self-check to each mermaid block before emitting it:
-- Each node/edge/subgraph label that contains anything other than letters, digits, and spaces (i.e. has `(` `)` `/` `&` `:` `,` `[` `]` `{` `}` `#` `@` `<` `>` `|` `"` etc.) MUST be wrapped in double quotes, with the quotes INSIDE the shape brackets (`API["ASP.NET API (v2)"]`, `DB[("SQL Server")]`).
+- Each node/edge/subgraph label that contains anything other than letters, digits, and spaces (i.e. has `(` `)` `/` `&` `:` `,` `[` `]` `{` `}` `#` `@` `<` `>` `|` `"` etc.) MUST be wrapped in double quotes, with the quotes INSIDE the shape brackets (`API["Orders API (v2)"]`, `DB[("Main database")]`).
 - No node id is a reserved word (lowercase `end`).
 - If you find a bare label in the source MD, **fix it in the emitted HTML** (quote it) rather than copying through a diagram you know will throw "Syntax error" in the browser. Note any such fix in the output summary so the author can also fix the MD source.
 
@@ -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.`
@@ -82,15 +84,15 @@ Invoke `render-workflow-docs {AppName}` as a subtask. Specifically:
 - `docs/{AppName}-Architecture.html` — if implementation revealed "as-built" deltas from "Target", update Architecture.md first, then re-render. Set status to "Current (post-implementation)" or "Current + planned target" as appropriate.
 - `PROJECT-STATUS.html` — always re-render (just updated in §2)
 
-Then re-render the **Usage Guide** (updated in §1) and the **DevGuide** (refreshed in §3a) via `.tfcore/tasks/generate-html.md`: `docs/{AppName}-UsageGuide.md` (+ the DevGuide — `docs/{AppName}-DevGuide.md` if single, or every file under `docs/devguides/` if split) → sibling `.html`. **Do NOT render the checklist to HTML** — it is an AI-agent working document kept in markdown only; its Status table stays accurate in markdown.
+Then re-render the **Usage Guide** (updated in §1) and the **DevGuide** (refreshed in §3a) via `.tfcore/tasks/generate-html.md`: `docs/{AppName}-UsageGuide.md` (+ `docs/{AppName}-DevGuide.md`) → sibling `.html`. **Do NOT render the checklist to HTML** — it is an AI-agent working document kept in markdown only; its Status table stays accurate in markdown.
 
 ### 3a. Refresh the Developer Guide
 
-Run `.tfcore/tasks/devguide.md` for `{AppName}` (`*devguide {AppName}`) so the screen-by-screen code map reflects the final as-built code — this is the doc a human developer uses to chase bugs and verify the AI-generated code from page → control → service → data-access → stored proc. If a DevGuide already exists, an incremental `--update` is enough (remap only changed screens). It produces `docs/{AppName}-DevGuide.md` (single) — or, for a large app, an index + per-role files under `docs/devguides/` — and their `.html`; §3 above already lists them in the re-render set.
+Run `.tfcore/tasks/devguide.md` for `{AppName}` (`*devguide {AppName}`) so the screen-by-screen code map reflects the final as-built code — this is the doc a human developer uses to chase bugs and verify the AI-generated code from page → control → service → data-access → stored proc. If a DevGuide already exists, an incremental `--update` is enough (remap only changed screens). It produces `docs/{AppName}-DevGuide.md`, one file at any size, and its `.html`; §3 above already lists them in the re-render set.
 
 ### 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/metrics-report.md

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

package/.claude/commands/TechieFlow/tasks/mockups.md

@@ -9,7 +9,7 @@ First: `bash .tfcore/utils/tf-phase.sh start mockups {App}` prints the start tim
 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.
+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` — for phase n of a Large project, `docs/{App}-Pn-UIDesign.md` from `app-phase-uidesign-tmpl.md`, which carries that phase's screens only (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.

package/.claude/commands/TechieFlow/tasks/productguide.md

@@ -26,7 +26,7 @@ The Product Guide documents the real running app. If the repo is doc-only / not
 ### 2. Gather the screen inventory + screenshots (reuse, don't reinvent)
 
 The DevGuide already did the hard discovery work — reuse it:
-- Read the **DevGuide** (`docs/{AppName}-DevGuide.md`, or the split set under `docs/devguides/`) for the role→menu map, the screen list, the real post-login landing per role (LANDING-TRUTH), and each screen's purpose.
+- Read the **DevGuide** (`docs/{AppName}-DevGuide.md`) for the role→menu map, the screen list, the real post-login landing per role (LANDING-TRUTH), and each screen's purpose.
 - Use the **screenshots** the DevGuide's OBSERVE pass captured under `docs/screenshots/{AppName}/` (`{role}-{screen-slug}.png`, + `-mobile` where present). These are the images the guide embeds.
 - Read the **BRD** §9 feature catalog (feature purpose/benefit, personas) and the **UsageGuide** (user flows + known limitations) for the plain-language "what it's for" and "tips".
 
@@ -34,7 +34,7 @@ The DevGuide already did the hard discovery work — reuse it:
 
 ### 3. Decide structure — single doc vs per-role split
 
-Same rule as devguide §3: **split per role** when `roles ≥ 3` OR `screens > 12` OR any role has `> 8` screens; else single. Honor `--single`/`--split`. A split guide lives in `docs/productguides/` (index + per-role files co-located, so relative links resolve); a single guide is `docs/{AppName}-ProductGuide.md`. On a structure switch (single↔split), move/delete the stale-location copy so only one canonical copy survives.
+**Split per role** when `roles ≥ 3` OR `screens > 12` OR any role has `> 8` screens; else single. Honor `--single`/`--split`. A split guide lives in `docs/productguides/` (index + per-role files co-located, so relative links resolve); a single guide is `docs/{AppName}-ProductGuide.md`. On a structure switch (single↔split), move/delete the stale-location copy so only one canonical copy survives.
 
 ### 4. Write the guide — END-USER voice, screenshot per screen (FAN OUT per role)
 

package/.claude/commands/TechieFlow/tasks/render-workflow-docs.md

@@ -6,7 +6,7 @@ Render BRD.html, Architecture.html, and PROJECT-STATUS.html from their markdown
 
 After day-1 (or any phase that changes BRD/Architecture/PROJECT-STATUS), regenerate the human-readable HTML mirrors. Self-contained single-file HTML with Mermaid rendering, copy buttons on every code block, mermaid toolbar (zoom/fit/1:1/fullscreen/popout), inline TOC, and sidebar TOC for long docs.
 
-**If the user has ad-hoc HUMAN-readable docs to render (library-feedback files, design notes, archived docs, anything else), use `*generate-html @path/to/file.md` instead — this task only handles the three canonical files.** Note: the **checklist is an AI-agent working document and is NEVER rendered to HTML** — do not render `*-Checklist.md` here or via `generate-html`.
+**If the user has ad-hoc HUMAN-readable docs to render (design notes, archived docs, anything else), use `*generate-html @path/to/file.md` instead — this task only handles the three canonical files.** Note: the **checklist is an AI-agent working document and is NEVER rendered to HTML** — do not render `*-Checklist.md` here or via `generate-html`. Nor are the miss log and feedback files.
 
 ## Inputs
 

package/.claude/commands/TechieFlow/tasks/triage-issues.md

@@ -6,9 +6,9 @@ First: `bash .tfcore/utils/tf-phase.sh start triage-issues {App}` prints the sta
 
 ## Steps
 
-1. Read every screenshot and the notes; from a written list take one issue per symptom in the reporter's words. Build the issue list: screen, role, symptom, evidence path, a first guess of kind (`layout`, `render-empty`, `data-logic`, `rag`).
+1. Read every screenshot and the notes; from a written list take one issue per symptom in the reporter's words. Build the issue list: screen, role, symptom, evidence path, a first guess of kind (`layout`, `render-empty`, `data-logic`, `rag`). A failed CI run (its id, link or log) is evidence too: its issue is the failing step and its first error.
 2. `bash .tfcore/utils/tf-verify-boot.sh start` boots the application (dependent services first, from their own configuration). Sign in as a UsageGuide test user (`.tfcore/tasks/_smoke-test-policy.md`). NONE means the issues are logged from the evidence alone and the report says the app was not booted.
-3. Reproduce each issue on its screen; `bash .tfcore/utils/tf-verify-screens.sh --screen <name>=<route> … --base <url>` gives the render and visual evidence and a screenshot. Settle the kind from what you see and map the issue to its row in the checklist (the acceptance line's screen; the DevGuide's screen list). Print the triage table: issue, row, kind, action.
+3. Reproduce each issue on its screen; `bash .tfcore/utils/tf-verify-screens.sh --screen <name>=<route> … --base <url>` gives the render and visual evidence and a screenshot. Settle the kind from what you see and map the issue to its row in the checklist (the acceptance line's screen; the DevGuide's screen list). Print the triage table: issue, row, kind, action. A CI failure is reproduced with `bash .tfcore/utils/tf-ci-repro.sh [<workflow>] [--job <id>]`, never by running the workflow's commands here: this machine's package caches and build output hide what a fresh runner hits (Lekhak TF-019: a runtime pack only the local NuGet cache held). Its FAIL line is the reproduction; a PASS means it could not be reproduced here, logged with `note`.
 4. Log each issue with `bash .tfcore/utils/tf-triage.sh {App} …`: `demote <REQ> "<symptom>" --kind … --evidence <path>` for a defect inside a row's scope, whatever its status; `new "<title>" "<When … on <screen>, then …>" --section "<screen>"` for a defect no row covers (a Not Started row with `BRD-pending`; new scope rather than a defect is still logged, and the report names `*amend-docs`); `note <REQ> "<what was tried>"` when it could not be reproduced. `--source production` for a live report. Whose gap it was is recorded as `--sort` (the four questions of `.tfcore/tasks/log-miss.md` step 1); without it a demoted row is `weak-check` (its line existed and the check let it through) and a new row is `spec`.
 5. With `verify`: execute `.tfcore/tasks/verify-phase.md` inline, scoped to the demoted rows' siblings on the same screens and any scope the owner named. Without it, the verifier does not run and nothing is re-checked informally.
 6. `bash .tfcore/utils/tf-verify-boot.sh stop`, then `bash .tfcore/utils/tf-triage.sh {App} close --started <the step-0 time>`: one escaped gate record per row (no check caught it), one miss per row in the reporter's words with the discovery cost, the run record, and a warning plus a miss if any code file changed during the run.

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

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