@techierathore/techieflow 1.0.1 → 1.0.3

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

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

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

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

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

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

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

@@ -1,157 +1,16 @@
 # triage-issues
 
-The **ANALYZE-ONLY** front door for bugs a human found by running the app — UAT feedback, production reports, an owner test session. Flow-master reproduces each reported issue, triages it to its owning screen + REQ, and delivers **documentation, not code**: checklist updates (demotions + new bug REQ rows), an optional scoped regression re-verify, DevGuide known-issues notes, and a PROJECT-STATUS refresh whose next-command points at the fix. **It NEVER changes source code and NEVER spawns builder sub-agents.** Fixing is a separate, later decision the owner makes by running `*fix-issues` (or `*build-phase`).
+`*triage-issues {App} {evidence} [verify]` is the analyse-only front door for bugs a person found by running the application: UAT feedback, a production report, an owner test session. The evidence is a folder of screenshots with an optional notes file, a written list, or both. The deliverable is the checklist and the telemetry, never code: nothing under `src/`, `source/` or `tests/` changes, and no builder is spawned. Fixing is the owner's next decision, `*fix-issues`. It honours YOLO.
 
-## Why this exists
+First: `bash .tfcore/utils/tf-phase.sh start triage-issues {App}` prints the start time; keep it.
 
-`*fix-issues` fixes — that is its deliverable. When the owner says "analyze these UAT bugs, re-verify the other features, and update the checklist", they want a **plan and a paper trail** — which REQs regressed, what is new, what still passes — WITHOUT an agent charging ahead and editing code nobody asked it to touch (that happened: AstroLyfe UAT, 2026-07-16 — an "analyze and log" request was routed into fixing). After this task runs, the checklist + PROJECT-STATUS fully describe the bugs, and NOTHING in `src/` or `tests/` has moved.
+## Steps
 
-## Inputs
-
-- `{AppName}` (required; or resolve from `core-config.yaml`).
-- `{Evidence}` — one or both of:
-  - a **folder** of screenshots (+ optional description file `bugs.md` / `README.md` / `notes.txt`) — the same evidence channel `*fix-issues` uses; and/or
-  - a **written bug list** — chat text or a file path (UAT/production reports often arrive as prose).
-  If neither is given, ask once for the folder path or the list.
-- `[verify]` (optional literal) — after logging, ALSO execute a scoped regression re-verify (§5). Without it, the verifier is not run at all.
-
-## HARD SCOPE RULE — read this before anything else
-
-**This task is read-only on the application.** You may boot and drive the app, but you MUST NOT edit anything under `src/` or `tests/`, MUST NOT spawn `/trblazeui`, `/techierag`, or any fixer sub-agent, and MUST NOT "quickly fix" anything you find — however obvious the one-liner. The only files you write: `docs/{AppName}-Checklist.md`, the DevGuide's known-issues lines, `PROJECT-STATUS.md` + `.html`, and (in `verify` mode) whatever an executed verify-phase legitimately writes. If the owner asks mid-run for a fix, that is a NEW command (`*fix-issues`) — finish the triage deliverables first, then say so.
-
-## SEQUENTIAL Execution
-
-### 0. Stamp the start time
-
-`date -u +%Y-%m-%dT%H:%M:%SZ` — keep it. It is this run's `started` and `run_id` for §6a.
-
-### 1. Ingest the evidence
-
-- If a folder was given: list it, **read every screenshot** (vision) and the description file if present.
-- If a written list was given: extract one issue per distinct symptom, keeping the owner's wording in the record.
-- Build a working list: `{ id, screen/route guess, role guess, symptom, evidence (image path or quoted words), kind-guess }` — kinds as in fix-issues: `layout`, `render-empty`, `data/logic`, `rag`. Final classification happens after repro (§3).
-
-### 2. Boot the app (per `_smoke-test-policy.md` + `verify-phase.md §Local-only`)
-
-- Boot it yourself via the build-invocation-ladder; dependent services in dependency order. "Can't run on Linux / it's MAUI / needs a GUI" are BANNED excuses; escalate per `verify-phase.md §3a`. Never propose a cloud deploy.
-- Resolve a test login from `docs/{AppName}-UsageGuide.md` / the DB — never auto-create a random user.
-
-### 3. Reproduce and triage each issue
-
-For each issue: log in as the relevant role, navigate to the screen, and **reproduce the symptom**. Apply the data-render gate (`verify-phase.md §4a`) and the visual-truth gate (`§4b`) OBSERVATIONALLY, settle the issue's kind from what you see, and map it to the owning screen + `REQ-*` in `docs/{AppName}-Checklist.md` (DevGuide screen→REQ map). An issue that does not reproduce is recorded as `could-not-reproduce` with what you tried — never guessed at.
-
-Echo a triage table — same shape as fix-issues §3, but the last column is the **checklist action**, not a builder:
-```
-Issue 1 → REQ-UI-007 (Dashboard) — kind: layout (KPI cards overlap chart)  → demote to Needs re-verify
-Issue 2 → REQ-FN-014 (Clients)   — kind: render-empty (16 count, 0 rows)   → demote to Needs re-verify
-Issue 3 → (no owning REQ — export button missing)                          → NEW row REQ-FN-021 (Planned)
-Issue 4 → REQ-RAG-003 (Assistant)— could-not-reproduce (answer rendered OK) → dated Remark + owner question
-```
-
-### 4. Log the bugs — the checklist IS the deliverable
-
-For each reproduced issue, in `docs/{AppName}-Checklist.md`:
-
-- **Regression of an existing REQ** (the broken behaviour is inside a REQ's scope, whatever its current status): set Status → `Needs re-verify`, adjust % per the guide, and add a dated Remark — `⚠ UAT bug {today}: {symptom} (evidence: {path or "owner report"}; kind: {kind})` (use `⚠ prod bug` for production reports). Demotions are always allowed — guard-verify never blocks them. **NEVER write `Verified` from this task.**
-- **Defect with no owning REQ** (behaviour that was never specified): append a NEW row — next free ID in the right prefix — Status `Planned`, Remark `logged from UAT {today}`, plus a detail bullet (with its `<a id="d-req-…">` anchor) in the matching section stating the ACCEPTANCE that would close it. If it is genuinely NEW SCOPE (a feature request, not a defect), still log the row but flag `*amend-docs` in the report — do not invent BRD text here.
-- **Could-not-reproduce**: a dated Remark on the nearest REQ (no status change) + a question for the owner in the report.
-
-### 5. Optional regression re-verify (`verify` argument only)
-
-The owner often wants "and check the rest still works". With `verify`: read `.tfcore/tasks/verify-phase.md` and **EXECUTE it inline** (skip its §0 question — scope is known), scoped to (a) the demoted REQs' siblings — other REQs owning the same screens/services — and (b) any scope the owner named. This is a real verify-phase run: it writes the `docs/.last-verify.json` ledger and may legitimately write `Verified` / `FAIL` verdicts. Without `verify`, skip this section entirely — do not "informally" re-check other features and write verdicts from it.
-
-### 6. Update the docs (status gate)
-
-- **DevGuide:** add/refresh the affected screens' Known-issues lines (cite the evidence screenshot). If a screen is not in the DevGuide yet, note it for `*devguide {AppName} --update` — do not run a full devguide pass here.
-- **PROJECT-STATUS (FINAL GATE, per `_status-update-gate.md`):** overwrite in place, `.md` AND `.html`. Phase reflects reality (open bug rows pull the project back to Build/Verify per the ladder). **Next command:** the bug rows just logged are build-tier work whose front door is **`*fix-issues {AppName} {Folder}`** — point there, naming the REQ IDs (fall back to `*build-phase {AppName}` when there is no evidence folder to hand it). Add a Verification-log row ONLY if §5 ran — triage by itself is not a verify pass.
-- **Never run git.**
-
-### 6a. Emit telemetry — this is where ESCAPE RATE comes from
-
-Doctrine: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §3.
-
-A bug reaching this task means **every gate missed it** — it got past acceptance, data-render, visual-truth and standards, and a human found it in UAT or production. That fact exists nowhere else in the framework, and it is the only way escape rate can be computed. Emit it.
-
-**One `gates.jsonl` record per REQ you demoted or newly logged in §4**, with `gate:"escaped"`:
-
-```bash
-ATT=$(bash .tfcore/utils/tf-emit.sh --next-attempt REQ-UI-009)
-cat <<JSON | bash .tfcore/utils/tf-emit.sh gates
-{"kind":"gate","app":"{AppName}","run_id":"<the run start timestamp>",
- "req_id":"REQ-UI-009","req_class":"UI","attempt":$ATT,"verdict":"Needs re-verify",
- "gate":"escaped","gates_run":[],"failure_class":"overlap","prior_verdict":"Verified"}
-JSON
-```
-
-- `gate` is **always `"escaped"`** here. Never name a real gate — none of them fired; that is the entire finding.
-- `gates_run` is `[]` — this task runs no gates. (Records written by the §5 verify pass are the verifier's, emitted by verify-phase §6a with real gate names. Do not duplicate them.)
-- `prior_verdict` is the Status you demoted **from** — `Verified` there is the strongest possible signal and must be recorded faithfully.
-- `failure_class` from the closed enum only. **Never the symptom text** — the symptom belongs in the checklist Remark, never in telemetry (constraint 7).
-- **Could-not-reproduce → emit nothing.** No defect was established; a record would inflate the escape rate with a non-event.
-- New `Planned` rows for never-specified behaviour: emit with `verdict:"FAIL"`, `prior_verdict:null` — the gap escaped just as surely, it simply had no REQ to escape from.
-
-**Then one `misses.jsonl` record per reproduced issue** (SCHEMA.md §5.5). The `escaped` gate record above says *no gate caught it*; the miss record says *what was missed and which phase let it through* — the two answer different questions and both are wanted.
-
-```bash
-MID=$(bash .tfcore/utils/tf-emit.sh --next-miss-id)
-cat <<JSON | bash .tfcore/utils/tf-emit.sh misses
-{"kind":"miss","miss_id":"$MID","req_id":"REQ-UI-009","req_class":"UI",
- "miss_class":"regression","artifact":"src","severity":"blocker",
- "why_missed":"insufficient-verify-method",
- "origin_phase":"build-phase","origin_agent":"trblazeui",
- "origin_run_id":"<started of the run that last touched this REQ, from runs.jsonl>",
- "found_by":"owner","found_phase":"triage-issues","found_gate":null,
- "found_run_id":"<this run's start>","failure_class":"overlap"}
-JSON
-```
-
-- **`found_by`** is `"owner"` for a UAT / owner test session and `"production"` for a live report. Nothing else — this field is what separates an in-cycle failure from a true escape, and it is the whole reason the record is worth writing.
-- **`found_gate` is `null`.** No gate fired; that is the finding.
-- **`why_missed` is NOT optional here.** Every record this task writes is an escape — it got past every gate and a human found it — so *why nothing caught it* is the entire value of the record, and the report warns when it is absent. Answer it from what you observed reproducing the bug: `missing-checklist-item` (no acceptance covered this behaviour), `insufficient-verify-method` (acceptance existed but no gate could have caught this), `code-audit-limitation` (the screen was never runtime-observable), `ambiguous-acceptance`, `dependency-not-declared`. This is the field that tightens the gates for next time.
-- **Run the `--open-miss` collapse check first**, exactly as verify-phase does: if this REQ already has an open miss of the same `miss_class`, the owner has found the same defect the gates already know about — emit nothing.
-- **A defect with no owning REQ** (a new `Planned` row in §4) is `req_id:null`, `miss_class:"unspecified-gap"`, `artifact:"brd"`. That combination is the single most valuable record in this stream: **it is a design miss, caught by a human, months after the phase that made it.**
-- **Could-not-reproduce → emit nothing**, for the same reason no `gates` record is written: no defect was established.
-
-Then one `runs.jsonl` record:
-
-```bash
-cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
-{"kind":"run","app":"{AppName}","cmd":"triage-issues","mode":null,
- "started":"<start>","ended":"<now>","duration_s":<n>,
- "reqs_touched":["REQ-UI-009"],"reqs_count":1,
- "subagents":[],"files_written":<n>,"build_result":"not-run"}
-JSON
-```
-
-`build_result` is `"not-run"` unless you actually built something (you did not — this task never touches code). **Telemetry has no veto:** a failed emit changes nothing and is not worth reporting.
-
-### 7. HALT — report (and DO NOT fix)
-
-```
-# Triage — {AppName}
-Evidence: {folder and/or written list} ({S} screenshots, {n} reported issues)
-Reproduced: {r} → {d} REQs demoted to Needs re-verify, {p} new Planned rows | Could-not-reproduce: {x} (questions below)
-Regression re-verify: {ran on <scope> — <pass>/<fail> | not requested}
-Docs: checklist + DevGuide known-issues + PROJECT-STATUS (.md + .html) updated
-NOTHING in src/ or tests/ was changed — fixing was not requested.
-Next: /TechieFlow:agents:flow-master *fix-issues {AppName} {Folder}   (OpenCode: /flow-master)   (targets: {REQ IDs})
-```
-
-## Hard rules
-
-- **Docs are the deliverable; code is untouchable.** No `src/`/`tests/` edits, no builder sub-agents, no "obvious one-liner" fixes. If you changed a source file, this task FAILED.
-- **Never write `Verified` from triage.** Demote freely; promotion happens only through the §5 EXECUTED verify-phase (which writes its own run ledger).
-- **Triage from what you OBSERVE** — reproduce live before logging; `could-not-reproduce` is a valid answer, never a licence to guess.
-- **Boot it yourself**; documented test users only; never auto-create one.
-- **Status gate is the last action** — PROJECT-STATUS `.md` AND `.html`; next command = the fix pointer with REQ IDs. Never run git.
-
-## Output Checklist
-
-- [ ] Evidence ingested — screenshots vision-read and/or prose parsed; issue list built
-- [ ] App booted (incl. dependent services); documented test user used
-- [ ] Every issue reproduced (or recorded could-not-reproduce) and mapped to screen + REQ — triage table echoed
-- [ ] Checklist updated — demotions with dated `⚠ UAT bug` remarks; new `Planned` rows with acceptance detail bullets
-- [ ] `verify` arg honoured (scoped verify-phase EXECUTED, ledger written) — or verifier untouched
-- [ ] DevGuide known-issues refreshed; PROJECT-STATUS `.md` + `.html` updated; next command = `*fix-issues` pointer with REQ IDs
-- [ ] ZERO source/test files modified; no builder sub-agent spawned
-- [ ] `gates.jsonl` record with `gate:"escaped"` emitted per demoted/new REQ, + one `misses.jsonl` `miss` per reproduced issue (`found_by:"owner"`/`"production"`, collapse-checked), + one `runs.jsonl` record (§6a)
+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`).
+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.
+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.
+7. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record is the one step 6 wrote. The next command is `*fix-issues {App} {evidence}` naming the rows.
+8. Report: evidence read, issues reproduced and logged (rows demoted, rows added), could-not-reproduce with the question for the owner, the verify scope if it ran, "no code changed", and the next command.