@techierathore/techieflow 1.0.0

package/.tfcore/tasks/refresh-status.md

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

package/.tfcore/tasks/render-workflow-docs.md

@@ -0,0 +1,117 @@
+# render-workflow-docs
+
+Render BRD.html, Architecture.html, and PROJECT-STATUS.html from their markdown sources.
+
+## Purpose
+
+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`.
+
+## Inputs
+
+- `{AppName}` argument (required).
+  - If absent, read `.tfcore/core-config.yaml` → `customTechnicalDocuments.brd` and extract the app name from `docs/{AppName}-BRD*.md`. If both are absent, ask: "Application name?"
+
+## SEQUENTIAL Execution
+
+### 1. Locate sources
+
+**Use the Read tool — NOT bash.** Bash file-existence checks trigger permission prompts; the Read tool is auto-allowed.
+
+For BRD and Architecture, locate the file using this priority:
+
+1. If `core-config.yaml` has `customTechnicalDocuments.brd` (or `.architecture`) pointing at a specific path, USE that path verbatim.
+2. Otherwise look for `docs/{AppName}-BRD.md` and any versioned variants matching `docs/{AppName}-BRD*.md` (e.g. `docs/{AppName}-BRD-v2.md`, `docs/{AppName}-BRD-old.md`, `docs/{AppName}-BRD-V3.md`). Same for Architecture. Top-level `docs/` ONLY — never scan `docs/OldDocs/` (the archive folder the day-1 tasks move superseded docs into; archived files are not render candidates). Since the day-1 collision policy (day1-brownfield §1.6) archives old versions instead of suffixing new ones, multiple variants should only occur in projects predating that policy.
+
+**If multiple variants are found, ASK before rendering** — list each candidate with its `Last updated:` value if visible, and ask which one to render. This is the one-and-only question this task may ask, and it's required to avoid the bug where a stale BRD gets rendered when a fresh versioned one (`-v2.md`) is sitting next to it.
+
+If the user wants to render a different file than what the canonical name pattern resolves to, tell them to use `*generate-html @docs/{the-file}.md` (plain path without `@` under OpenCode) and HALT.
+
+PROJECT-STATUS is always at the repo root: `PROJECT-STATUS.md`.
+
+Read each of the three resolved files. If any required source is missing, HALT and tell the user which is missing + suggest `*day1-brownfield` / `*day1-greenfield`.
+
+For the "Last rendered" subtitle, use today's date — do not bash-fetch file mtimes.
+
+### 2. Render with the framework renderer — one command for every document
+
+```bash
+bash .tfcore/utils/tf-render-html.sh docs/{AppName}-BRD.md docs/{AppName}-Architecture.md PROJECT-STATUS.md
+```
+
+`tf-render-html.sh` implements `.tfcore/templates/v4custom/html-render-shell.md` in full and reads that spec's §2 CSS / §3 theme script / §7 JS **at render time**, so a rendered page cannot drift from the shell — the drift that used to break the mermaid toolbar, the copy buttons and the TOC links is now structurally impossible.
+
+Pass every document in ONE invocation; it renders each to a sibling `.html` (same directory, same basename). It refuses `*-Checklist.md` with exit 2.
+
+Hand-authoring these files through the Write tool is no longer the path (TfLens TF-003, 2026-08-27): it burned 75–80k output tokens per phase, could not be reproduced run-to-run, and a 130 KB file emitted in one generation could silently truncate with no gate to catch it.
+
+`html-render-shell.md` stays the specification — read it to understand or change the shell, not to render.
+
+### 3. Render `docs/{AppName}-BRD.html` (or the chosen variant's `.html` sibling)
+
+**Rendered by `tf-render-html.sh` in step 2** — do not hand-author it, and do not bash-heredoc it. This step documents what the output must contain so you can check it, not how to build it.
+
+Output path: same directory as the source MD, same basename, `.html` extension (so `docs/{App}-BRD-v2.md` → `docs/{App}-BRD-v2.html`).
+
+Apply the full shell. Title: `{AppName} — Business Requirements`. Subtitle: `Last rendered: {today YYYY-MM-DD}`.
+
+BRDs typically have ~12 H2 sections (Executive summary, Objectives, Scope, …, Glossary) — the sidebar TOC condition (>6 H2) almost always triggers. Inline TOC is always present.
+
+### 4. Render `docs/{AppName}-Architecture.html` (or chosen variant's `.html` sibling)
+
+Same as §3. Title: `{AppName} — Architecture`. Subtitle: `Last rendered: {today YYYY-MM-DD} · Status: {value of "Status:" line from source MD}`.
+
+Architecture docs typically have 7–9 H2 sections — usually >6, so sidebar TOC triggers. Inline TOC always present.
+
+### 5. Render `PROJECT-STATUS.html`
+
+Apply the shell. Title: `{AppName} — Project Status`. Subtitle: `Last rendered: {today YYYY-MM-DD}`.
+
+PROJECT-STATUS usually has 4–6 H2 sections — under the >6 threshold, so NO sidebar (use the `no-toc` class on `.layout`). Inline TOC may still appear if ≥2 H2.
+
+**`tf-render-html.sh` emits the "NEXT COMMAND TO RUN" call-to-action box itself** (since 2026-08-31, TfLens TF-010) — you do not add it, and you must not hand-patch it in afterwards. It special-cases `PROJECT-STATUS.md`, reads the **first fenced code block under `## Next command to run`**, and emits this markup immediately after the subtitle `<div>`, above the frontmatter table and the inline TOC:
+
+```html
+<div class="cta-next" style="padding:20px; background:var(--cta-bg); border:2px solid var(--accent); border-radius:10px; margin:20px 0;">
+  <div style="font-size:11px; color:var(--muted); letter-spacing:.5px;">NEXT COMMAND TO RUN</div>
+  <div style="font-family:var(--mono); font-size:18px; margin-top:6px;">{first line of that code block}</div>
+</div>
+```
+
+Theme variables only, never a hex — that is what `--cta-bg` is for, in both palettes.
+
+**If the box is missing, the source is missing, not the render.** The renderer emits nothing when `## Next command to run` is absent or its code block is empty — an absent box is honest, an invented command is not. Fix `PROJECT-STATUS.md` per `_status-update-gate.md` and re-render; do not edit the HTML.
+
+> **Why this is worth a paragraph.** From TF-003 (when hand-authoring moved into the script) until 2026-08-31 this section *required* the box and the renderer never emitted one, so the Output Checklist item below was unfalsifiable by reading the task, and the only workaround — patching the generated HTML — was overwritten by the next render. The tell was `--cta-bg`: a shell variable defined in both palettes and used by nothing.
+
+Render the frontmatter (project, stack, current_phase, last_verified_build, last_verified_date) as a clear definition list near the top.
+
+### 6. Verify each HTML mentally (per shell §9)
+
+This is a review of what you Wrote — do NOT shell out to an HTML validator. Confirm:
+
+- Every heading id matches the TOC link slug.
+- Every mermaid fence is wrapped in `<div class="diagram">` with the full 6-button toolbar.
+- **Mermaid validity pass (shell §5.5):** every node/edge/subgraph label containing non-alphanumeric characters is double-quoted (quotes inside the shape brackets), and no node id is the reserved word `end`. Fix any bare label in the emitted HTML rather than rendering a diagram that throws "Syntax error" in the browser.
+- Copy buttons will be added by the JS (no need to verify visually — but make sure the JS block is intact).
+- Sidebar TOC present iff H2 count > 6.
+- The two CDN scripts are present (mermaid, svg-pan-zoom).
+
+### 7. Output summary
+
+List the three written file paths (one per line). End with: `Open each in a browser to confirm Mermaid renders correctly. Code blocks have copy buttons; diagrams have a zoom/fit/1:1/fullscreen/popout toolbar.`
+
+## Output Checklist
+
+- [ ] All three sources located (BRD/Architecture variants resolved with user input if multiple matched)
+- [ ] Shared shell applied to every output (no hand-rolled palettes)
+- [ ] `docs/{AppName}-BRD.html` (or chosen variant) self-contained
+- [ ] `docs/{AppName}-Architecture.html` (or chosen variant) self-contained
+- [ ] `PROJECT-STATUS.html` self-contained, and its "NEXT COMMAND TO RUN" call-to-action present — **check it with `grep -c "NEXT COMMAND TO RUN" PROJECT-STATUS.html`, which must print `1`.** The renderer emits it (§5); a `0` means `PROJECT-STATUS.md` has no `## Next command to run` code block, which is a status-gate defect to fix in the markdown — never by editing the HTML.
+- [ ] Mermaid blocks wrapped in `.diagram` with toolbar
+- [ ] Mermaid validity pass done (shell §5.5): every non-trivial label double-quoted, no `end` node ids, bare labels fixed not emitted
+- [ ] Copy-button JS + mermaid toolbar JS present in each file
+- [ ] Inline TOC present where H2 count ≥ 2
+- [ ] Sidebar TOC present where H2 count > 6
+- [ ] Every TOC link has a matching heading `id` (shell §1 slug rule)

package/.tfcore/tasks/shard-doc.md

@@ -0,0 +1,185 @@
+# Document Sharding Task
+
+## Purpose
+
+- Split a large document into multiple smaller documents based on level 2 sections
+- Create a folder structure to organize the sharded documents
+- Maintain all content integrity including code blocks, diagrams, and markdown formatting
+
+## Primary Method: Automatic with markdown-tree
+
+[[LLM: First, check if markdownExploder is set to true in .tfcore/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+
+If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
+
+If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
+
+1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+2. Or set markdownExploder to false in .tfcore/core-config.yaml
+
+**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
+
+If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
+
+1. Set markdownExploder to true in .tfcore/core-config.yaml
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]
+
+### Installation and Usage
+
+1. **Install globally**:
+
+   ```bash
+   npm install -g @kayvan/markdown-tree-parser
+   ```
+
+2. **Use the explode command**:
+
+   ```bash
+   # For PRD
+   md-tree explode docs/prd.md docs/prd
+
+   # For Architecture
+   md-tree explode docs/architecture.md docs/architecture
+
+   # For any document
+   md-tree explode [source-document] [destination-folder]
+   ```
+
+3. **What it does**:
+   - Automatically splits the document by level 2 sections
+   - Creates properly named files
+   - Adjusts heading levels appropriately
+   - Handles all edge cases with code blocks and special markdown
+
+If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
+
+---
+
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
+
+### Task Instructions
+
+1. Identify Document and Target Location
+
+- Determine which document to shard (user-provided path)
+- Create a new folder under `docs/` with the same name as the document (without extension)
+- Example: `docs/prd.md` → create folder `docs/prd/`
+
+2. Parse and Extract Sections
+
+CRITICAL AEGNT SHARDING RULES:
+
+1. Read the entire document content
+2. Identify all level 2 sections (## headings)
+3. For each level 2 section:
+   - Extract the section heading and ALL content until the next level 2 section
+   - Include all subsections, code blocks, diagrams, lists, tables, etc.
+   - Be extremely careful with:
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
+     - Mermaid diagrams - preserve the complete diagram syntax
+     - Nested markdown elements
+     - Multi-line content that might contain ## inside code blocks
+
+CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
+
+### 3. Create Individual Files
+
+For each extracted section:
+
+1. **Generate filename**: Convert the section heading to lowercase-dash-case
+   - Remove special characters
+   - Replace spaces with dashes
+   - Example: "## Tech Stack" → `tech-stack.md`
+
+2. **Adjust heading levels**:
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
+   - All subsection levels decrease by 1:
+
+   ```txt
+     - ### → ##
+     - #### → ###
+     - ##### → ####
+     - etc.
+   ```
+
+3. **Write content**: Save the adjusted content to the new file
+
+### 4. Create Index File
+
+Create an `index.md` file in the sharded folder that:
+
+1. Contains the original level 1 heading and any content before the first level 2 section
+2. Lists all the sharded files with links:
+
+```markdown
+# Original Document Title
+
+[Original introduction content if any]
+
+## Sections
+
+- [Section Name 1](./section-name-1.md)
+- [Section Name 2](./section-name-2.md)
+- [Section Name 3](./section-name-3.md)
+  ...
+```
+
+### 5. Preserve Special Content
+
+1. **Code blocks**: Must capture complete blocks including:
+
+   ```language
+   content
+   ```
+
+2. **Mermaid diagrams**: Preserve complete syntax:
+
+   ```mermaid
+   graph TD
+   ...
+   ```
+
+3. **Tables**: Maintain proper markdown table formatting
+
+4. **Lists**: Preserve indentation and nesting
+
+5. **Inline code**: Preserve backticks
+
+6. **Links and references**: Keep all markdown links intact
+
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
+
+### 6. Validation
+
+After sharding:
+
+1. Verify all sections were extracted
+2. Check that no content was lost
+3. Ensure heading levels were properly adjusted
+4. Confirm all files were created successfully
+
+### 7. Report Results
+
+Provide a summary:
+
+```text
+Document sharded successfully:
+- Source: [original document path]
+- Destination: docs/[folder-name]/
+- Files created: [count]
+- Sections:
+  - section-name-1.md: "Section Title 1"
+  - section-name-2.md: "Section Title 2"
+  ...
+```
+
+## Important Notes
+
+- Never modify the actual content, only adjust heading levels
+- Preserve ALL formatting, including whitespace where significant
+- Handle edge cases like sections with code blocks containing ## symbols
+- Ensure the sharding is reversible (could reconstruct the original from shards)

package/.tfcore/tasks/split-brd.md

@@ -0,0 +1,131 @@
+# split-brd
+
+Split the BRD into the single AI-targeted requirement doc: the app Checklist (`docs/{AppName}-Checklist.md`).
+
+## Purpose
+
+The BRD captures business intent with `BRD-N` IDs. Implementation needs finer-grained, type-tagged requirements. There is **one checklist per app**; the requirement *type* is carried by the REQ prefix, which routes work to the right builder:
+- `REQ-UI-*` → built by `/trblazeui` (from the approved mockups), invoked as a sub-agent by the unified `build-phase`
+- `REQ-RAG-*` → built by `/techierag`, invoked as a sub-agent by `build-phase`
+- `REQ-FN-*` / `REQ-NFR-*` → built directly by `build-phase` (flow-master)
+
+This task converts each `BRD-N` into one or more `REQ-*` items inside the one checklist.
+
+## Inputs
+
+- `{AppName}` argument (required; or resolve from core-config.yaml).
+
+## SEQUENTIAL Execution
+
+### 1. Load inputs
+
+- `docs/{AppName}-BRD.md` — must exist. Parse `BRD-N` IDs and their text.
+- `docs/{AppName}-Architecture.md` — read for module boundaries and stack.
+- `docs/{AppName}-UIDesign.md` + `docs/mockups/*.html` — if they exist (greenfield, post-`*mockups`), read them so each `REQ-UI-*` cites the mockup screen it realizes.
+
+### 2. Classify each BRD-N
+
+For each `BRD-N`, classify as UI / FN / RAG / NFR:
+- **UI**: any user-visible change — page, component, form, dashboard, layout.
+- **RAG**: anything involving LLM, embedding, vector search, chat, prompt templates, token tracking, tool calling.
+- **NFR**: performance, security, accessibility, observability, compliance.
+- **FN**: everything else — backend logic, data, APIs, integrations, business rules.
+
+A single `BRD-N` may map to multiple REQs (e.g. a "settings page that saves to DB" splits into REQ-UI-N (the page) and REQ-FN-N (the save handler)).
+
+### 2.5. Dev-plan seeding (CONDITIONAL — brownfield projects with an existing plan)
+
+Check `docs/` for an existing development/phase plan (`*Development-Plan*.md`, `*Dev-Plan*.md`, `*Implementation-Plan*.md`, `*Roadmap*.md`, or any doc structured as Phase 0/1/2… with build order/statuses). If one exists:
+
+- Carry its phase structure into §3 — tag each REQ with its phase (e.g. `(BRD-21, Phase 1)`) and order rows by phase.
+- **Preserve every column the plan tracked** — the Requirements Status table must be a SUPERSET of the plan's, never a lossy summary. For each migrated REQ fill Status, **%**, **Remarks**, Details: carry the plan's `% Done` verbatim and its full dated status remark (e.g. "Completed 2026-04-30 (DTOs split…)") into Remarks — do not truncate.
+- COMPLETE/done/shipped → Status `Done (pre-existing)`, `%` = plan's figure (usually `100%`), Remarks = plan's note + `per {plan-file} §{section}`. Build agents must NOT rebuild these. Partial → `In Progress`/`PARTIAL` with the plan's `%`+remark. Not started → `Not Started`, `0%`.
+- Add a header note to the checklist: `> Migrated from {plan-file} on {YYYY-MM-DD}. Phase structure, completion %, and status remarks carried over verbatim — verify before building.`
+- Do not modify the plan file's content. After migration it is superseded — move it unchanged to `docs/OldDocs/` (create the folder if missing; date-suffix on name collision) and note this in the §6 summary.
+
+If no plan exists, skip — classify purely from the BRD.
+
+### 3. Write `docs/{AppName}-Checklist.md`
+
+Schema per `.tfcore/templates/v4custom/app-checklist-tmpl.md` — the **Requirements Status** table sits at the TOP (single source of truth for the WHOLE app), with all REQ classes in one table, and the per-REQ detail follows in prefix-grouped sections with `<a id="d-REQ-ID">` anchors the Details column links to:
+```markdown
+# {AppName} — Checklist
+
+## Goal
+{one paragraph; ties back to BRD §1}
+
+## Requirements Status
+| ID | Requirement | Status | % | Remarks | Details |
+|----|-------------|--------|---|---------|---------|
+| REQ-UI-001  | {short name} | Not Started | 0% | — | [view](#d-req-ui-001) |
+| REQ-FN-001  | {short name} | Not Started | 0% | — | [view](#d-req-fn-001) |
+| REQ-RAG-001 | {short name} | Not Started | 0% | — | [view](#d-req-rag-001) |
+| REQ-NFR-001 | {short name} | Not Started | 0% | — | [view](#d-req-nfr-001) |
+{Status values + % guide + Remarks note — copy the legend from the template}
+
+## UI / Pages
+### Page: {page name} (`{route}`)
+<a id="d-req-ui-001"></a>
+- **REQ-UI-001** — {description; traces to BRD-X}. *Mockup:* docs/mockups/{screen}.html (if mockups exist).
+  - *Acceptance:* {specific testable criterion}; controls do not overlap at desktop + mobile widths (visual gate).
+
+## Functional requirements
+<a id="d-req-fn-001"></a>
+- **REQ-FN-001** — {trigger / acceptance} (BRD-X)
+
+<!-- If the source BRD NFR carried a `perf-budget:` line, copy it into the REQ's Acceptance
+     bullet VERBATIM — same grammar, same numbers. verify-phase §4c reads it literally and
+     grades speed only where it exists. Never synthesize one for an NFR that lacked it, and
+     never drop one that was there: both silently change what "Verified" means for that REQ. -->
+
+
+## RAG / AI requirements (→ /techierag)
+<a id="d-req-rag-001"></a>
+- **REQ-RAG-001** — {trigger / acceptance via TechieRag} (BRD-X)
+
+## Non-functional
+<a id="d-req-nfr-001"></a>
+- **REQ-NFR-001** — {perf/security/accessibility} (BRD-X)
+```
+
+Cross-link: every REQ-N's description ends with `(BRD-X)` so traceability is two-way.
+
+### 4. Trace check
+
+- Every `BRD-N` should appear at least once in the checklist's Requirements Status table.
+- If any `BRD-N` is unmapped, list it in the output summary and ask: "BRD-X has no REQ. Is it deferred, or should I map it now?"
+
+### 5. Output summary
+
+Report counts:
+- `K` `REQ-UI-*`, `M` `REQ-FN-*`, `N` `REQ-RAG-*`, `P` `REQ-NFR-*` items in the checklist
+- Any unmapped `BRD-N`s flagged in §4
+
+Update `PROJECT-STATUS.md` per `.tfcore/tasks/_status-update-gate.md` (this task counts as a phase — the gate applies):
+- Next phase is always the unified build while any REQ is open: current_phase `Build`, Next command `/TechieFlow:agents:flow-master *build-phase {AppName}` (OpenCode: `/flow-master *build-phase {AppName}`). `build-phase` clusters all open REQs and calls `/trblazeui` (REQ-UI-*, from the mockups) and `/techierag` (REQ-RAG-*) as sub-agents itself — you do NOT point the user at a separate UI or RAG command.
+- `last_updated`: today. Leave `last_verified_build`/`last_verified_date` as-is (no build this phase).
+- Sync "Open requirements" to the new Status table (everything non-terminal).
+- Append a row to "Verification log" — N/A (no verify yet)
+- List unmapped open requirements if any
+- Re-render `PROJECT-STATUS.html` (gate minimum #8). Do NOT render the checklist to HTML — it is an AI-agent working document (markdown only).
+
+### 6. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"split-brd","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+## Output Checklist
+
+- [ ] `docs/{AppName}-Checklist.md` exists with REQ-UI/FN/RAG/NFR-* IDs each back-linking to BRD-N, in one Requirements Status table
+- [ ] Every `BRD-N` is mapped or explicitly deferred
+- [ ] `PROJECT-STATUS.md` updated with `Build` phase + `*build-phase` next command (+ re-rendered HTML)