@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/templates/stack-defaults/dotnet.md

@@ -0,0 +1,35 @@
+# TechieFlow — Stack Defaults: .NET
+
+| | |
+|---|---|
+| Purpose | An answer set for `TechieFlow-Stack-Questions.md`. These are the defaults the framework's author uses for their own .NET / Blazor / MAUI projects. Naming this answer set at day-1 fills in the questions it covers; the agent asks the rest. |
+| Audience | Owners of .NET projects using TechieFlow. Owners in other stacks write their own answer set with the same structure. |
+| Status | Drafted in Session 2 of the reset (2026-09-04) from the author's answers. Becomes a file under `.tfcore/templates/stack-defaults/` in Session 3. Configuration document read by agents; not rendered to HTML. |
+| Applies to | Projects that declare `stack: dotnet` and name this answer set. Change any row for a project by overriding it in that project's Architecture Stack Decisions section; the override wins. |
+
+---
+
+## Answers
+
+| Q | Topic | Default | Still asked at day-1? |
+|---|---|---|---|
+| Q1 | Configuration | Non-secret configuration lives in `appsettings.json`, layered by `appsettings.{Environment}.json`. No other configuration mechanism is created. | No |
+| Q2 | Secrets in development | Project user secrets (`dotnet user-secrets`), visible to the developer, never committed. `appsettings.Development.json` is committed and therefore never holds a real secret. A `secrets.example.json` in the project lists every key the application reads. | No |
+| Q3 | Database | PostgreSQL, running in Docker, for development and production. Docker is always running on the development machine because WSL, where the harness runs, depends on it. If PostgreSQL is unreachable the container is stopped: the agent starts it and continues. Only if no PostgreSQL container exists at all does the agent stop and ask the owner for connection details. It never substitutes another engine and never creates its own database container. | No, unless no container exists |
+| Q4 | Authentication | Two choices only: **AppManager**, the author's shared platform for identity, roles, licences and subscriptions, which counts as part of the application and not as an external integration; or a different mechanism named by the owner. | **Yes**: "AppManager, or something else?" |
+| Q5 | Logging | Serilog, always, with file logging wired at startup before anything else can fail. | No |
+| Q6 | Tests | xUnit, always. A test project exists from day-1. | No |
+| Q7 | Layout and naming | `src/` and `tests/` at the root. The primary executable project is named exactly `<App>`; `<App>.App` is banned. Secondary heads take a descriptive suffix (`<App>.Api`, `<App>.Desktop`). | No |
+| Q8 | User interface | TrBlazeUI for every Blazor head and every MAUI Blazor Hybrid head. Native controls for WinForms, WPF and non-Blazor MAUI heads. Rendering mode is chosen per project and recorded. | Rendering mode only |
+| Q9 | Hosting | Web applications run containerised on a Bluehost VPS. The owner supplies a pipeline guidance document at UAT go-ahead, and a deployment checklist is produced from it. | Asked at UAT go-ahead, as the questionnaire specifies |
+| Q10 | Production secrets | Decided when the owner asks for the production pipeline, after UAT. Until then no document states where production secrets live. | Asked after UAT |
+| Q11 | Standing rules and prohibitions | 1. Never add a NuGet package without a line in the Architecture document saying why. 2. Never create a second configuration mechanism. 3. When TechieFlow, TrBlazeUI, TechieRag or any other internal library lacks something, record it in that library's feedback file and hold the feature until the library is fixed. Never implement a workaround. 4. Data access is always Dapper. 5. Database migrations live in a dedicated project named `<App>Db` (console or library) using the DbUp package. The web application runs the migration at startup, or the pipeline runs it after deployment. Never a `database` folder of loose scripts at the repository root. 6. Log files are written under the build output folder (`bin/`), which is git-ignored. Never at the repository root. 7. No unnecessary folders at the repository root (`data`, `database`, `scripts` and the like). Everything sits under `src/` or `tests/` according to what it belongs to. | No |
+
+---
+
+## Notes
+
+- Q4 is asked on purpose even with this answer set, because the choice differs per product.
+- Q3's "start the container, never create one" replaces the behaviour that produced TfLens's own database container: an agent that cannot reach the expected database restarts it or asks, and never builds an alternative.
+- Q11.5 replaces the `database` folder of loose migration scripts that TfLens accumulated.
+- Q11.3 is a standing framework convention restated as a stack rule so that it is recorded per project and its violations can be counted.

package/.tfcore/templates/stack-questions.md

@@ -0,0 +1,77 @@
+# TechieFlow — Stack Questions
+
+| | |
+|---|---|
+| Purpose | The questions the framework asks the owner about a project's technology and conventions, when it asks them, and where the answers are recorded. The framework itself is technology-neutral; these answers are what make a project's documents and code specific. |
+| Audience | Framework agents (the questionnaire is asked verbatim), project owners, contributors. |
+| Status | Drafted in Session 2 of the reset (2026-09-04). Becomes a template under `.tfcore/templates/` in Session 3. Configuration document read by agents; not rendered to HTML. |
+| Related | `TechieFlow-Stack-Defaults-DotNet.md` (an answer set), `TechieFlow-Requirements.md` (FR-01, FR-02) |
+
+---
+
+## 1. Principle
+
+The framework never assumes a language, a UI library, a database, an authentication scheme, a test framework or a hosting target. Before any project document is written, the agent asks the questions below and records the answers in one place: the **Stack Decisions** section of the project's Architecture document. Every later command reads its stack facts from there and nowhere else.
+
+An owner who always works in one stack answers once by naming an **answer set**, a file that holds their standard answers. The framework ships one answer set, `TechieFlow-Stack-Defaults-DotNet.md`, described as the defaults its author uses for their own .NET projects. Any owner may copy it, change it, or write a different one. Naming an answer set fills in every question it covers; the agent then asks only the questions the set leaves open.
+
+---
+
+## 2. When the questions are asked
+
+| Moment | Questions | Why then |
+|---|---|---|
+| Day-1, before any document is written | Q1 to Q8 | Every document depends on the answers. |
+| When the owner gives the go-ahead for user acceptance testing (UAT) | Q9 | Hosting decisions made earlier are guesses; by UAT the application is real. |
+| When the owner asks for a production deployment pipeline, after UAT | Q10 | Production secrets and infrastructure are decided by the people who run production. |
+
+In YOLO mode the agent does not skip the day-1 questions; it takes the answer set's value where one exists and stops with a clear message where none does. A document written without a recorded answer is a defect.
+
+---
+
+## 3. The questions
+
+**Q1. Configuration.** Where does non-secret configuration live, and how is it layered per environment?
+
+**Q2. Secrets in development.** Where do secrets live on a developer machine, and what must never be committed?
+
+**Q3. Database.** Which database engine in development and which in production? Is a container for the database acceptable, and under what condition? What does the agent do if the database is not reachable?
+
+**Q4. Authentication and authorisation.** Which identity mechanism: a shared platform, the framework's built-in identity, an external provider, or none? Who owns roles, licences and subscriptions?
+
+**Q5. Logging.** Which logging library, which sinks, and is file logging mandatory?
+
+**Q6. Tests.** Which test framework? Is a test project mandatory from day one? Which categories of test are expected (unit, integration, browser)?
+
+**Q7. Solution layout and naming.** Folder layout for source and tests; naming rule for the primary executable project and for secondary heads.
+
+**Q8. User interface.** Which UI framework or component library for each kind of head (web, mobile, desktop)? Which rendering mode by default?
+
+**Q9. Hosting and deployment.** Where does the application run, in what form (container, service, static files), and is there a deployment guidance document to follow? Is a deployment checklist required?
+
+**Q10. Production secrets and pipeline.** Where do production secrets live, and how does the pipeline inject them?
+
+**Q11. Standing rules and prohibitions.** Anything an agent must always or never do in this repository that is not already enforced by a hook. Recorded as a list; the framework treats each item as a rule and tracks whether it is honoured. Two rules are present by default in every project, whatever the stack, and an owner may remove them only by saying so:
+
+1. Log files are written under the build output folder, which is git-ignored. Never at the repository root.
+2. No unnecessary folders at the repository root (`data`, `database`, `scripts` and the like). Everything sits under the source folder or the tests folder according to what it belongs to.
+
+---
+
+## 4. Where the answers go
+
+The Architecture document gains a section, **Stack Decisions**, placed first, one row per question:
+
+| Q | Decision | Source | Date |
+|---|---|---|---|
+| Q1 | `appsettings.json` plus `appsettings.{Environment}.json` | answer set: DotNet | 2026-09-04 |
+| Q3 | PostgreSQL in a container for development and production | owner, day-1 | 2026-09-04 |
+| … | | | |
+
+"Source" is either the answer set name or "owner" with the moment it was asked. Q9 and Q10 rows are added when they are answered; until then they read "not yet asked (UAT)" and "not yet asked (production)". The Coding Standards document references this section instead of restating it.
+
+---
+
+## 5. What this replaces
+
+Before this document, the framework had one standing technology decision (Serilog file logging) written into the day-1 tasks, the BRD template and the Architecture template, and no place for any other. Projects therefore invented their own arrangements at build time; TfLens ended with settings in three places. This questionnaire moves every such decision to day-1 and to one recorded location.

package/.tfcore/templates/v4custom/app-agents-md-tmpl.md

@@ -1,7 +1,7 @@
 # {AppName} — project session memory (all harnesses)
 
 <!-- This file is COMMITTED (unlike CLAUDE.md, which is gitignored and imports it).
-     OpenCode and Codex auto-load AGENTS.md; Claude Code loads it through CLAUDE.md's
+     OpenCode auto-loads AGENTS.md; Claude Code loads it through CLAUDE.md's
      @AGENTS.md import. Keep everything in here harness-neutral — Claude-only
      material (permissions, tool preference) lives in app-claude-md-tmpl.md. -->
 
@@ -13,9 +13,9 @@ ALWAYS read and follow:
 
 ## Hard rules (non-negotiable — the harness enforces #1)
 
-1. **Git is manual — agents NEVER run `git` or `gh`.** Not to commit, and not to read (`status`/`log`/`diff`/`grep`/`blame`). All harnesses enforce this mechanically: Claude Code via `.claude/settings.json` and `block-git.sh`; OpenCode via `opencode.jsonc` plus its plugin bridge; Codex via `.codex/rules/techieflow.rules` plus `.codex/hooks.json`. A blocked git call is the policy working, not an obstacle to route around. Evidence for status updates / "what changed" = the checklist Requirements Status table + the working-tree files (+ mtimes) + a fresh `dotnet build` (`.tfcore/tasks/_status-update-gate.md`). The OWNER commits, in a separate terminal.
+1. **Git is manual — agents NEVER run `git` or `gh`.** Not to commit, and not to read (`status`/`log`/`diff`/`grep`/`blame`). All harnesses enforce this mechanically: Claude Code via `.claude/settings.json` and `block-git.sh`; OpenCode via `opencode.jsonc` plus its plugin bridge. A blocked git call is the policy working, not an obstacle to route around. Evidence for status updates / "what changed" = the checklist Requirements Status table + the working-tree files (+ mtimes) + a fresh `dotnet build` (`.tfcore/tasks/_status-update-gate.md`). The OWNER commits, in a separate terminal.
 2. **Run the app yourself — the test harness is fully set up.** Headless Playwright + Chromium live in WSL; the Windows/MAUI dotnet bridge is rung #4 of the build ladder; MAUI Android/iOS/Mac Catalyst are driven over the Appium bridge (`core-config.yaml → runtimeVerification.appium`). NEVER ask the owner to boot the app, run a build, or execute a command — "can't run on Linux/WSL", "it targets Windows", "it's MAUI", "Playwright needs a GUI", "the dependent service is down" are BANNED excuses (`.tfcore/tasks/_smoke-test-policy.md`). Asking the owner is the LAST resort, only after the build ladder + `verify-phase §3a` escalation genuinely fail — and even then you still run the test yourself once they reply.
-3. **The framework tree is invisible to search — a search that finds nothing is NOT proof a file is missing.** `.tfcore/`, `.claude/`, `.codex/`, `.opencode/` and `.agents/skills/` are hidden dot-directories AND gitignored here (deliberate — deployed framework copies are never committed). File search skips hidden paths *and* honours `.gitignore`, so it takes **both** (`rg -uu`; `--hidden` alone is not enough), and `git grep`/`git ls-files` see nothing at all. Confirm a framework file by **reading its literal path** — every one has a single canonical location, and whatever needs it names that path. Never write "not present in this tree" into a verdict, a checklist Remarks cell, a BRD row, or a blocker without having tried the path and failed: that false negative propagates into the docs and the next agent treats it as fact. If a framework file really is absent, the repo needs `update-framework.sh <repo>` run once on this machine — report that instead of reimplementing what it does. (`.tfcore/tasks/_status-update-gate.md` §"The framework tree is INVISIBLE to search".)
+3. **The framework tree is invisible to search — a search that finds nothing is NOT proof a file is missing.** `.tfcore/`, `.claude/`, `.opencode/` and `.agents/skills/` are hidden dot-directories AND gitignored here (deliberate — deployed framework copies are never committed). File search skips hidden paths *and* honours `.gitignore`, so it takes **both** (`rg -uu`; `--hidden` alone is not enough), and `git grep`/`git ls-files` see nothing at all. Confirm a framework file by **reading its literal path** — every one has a single canonical location, and whatever needs it names that path. Never write "not present in this tree" into a verdict, a checklist Remarks cell, a BRD row, or a blocker without having tried the path and failed: that false negative propagates into the docs and the next agent treats it as fact. If a framework file really is absent, the repo needs `update-framework.sh <repo>` run once on this machine — report that instead of reimplementing what it does. (`.tfcore/tasks/_status-update-gate.md` §"The framework tree is INVISIBLE to search".)
 4. **Native-head automation binds to the app's own window.** Drive a MAUI head only through a session attached to the app under test (Windows: launched PID → its top-level window handle; Android/iOS/Catalyst: the app's package/bundle id), interact element-by-element via `AutomationId`, and NEVER inject global keyboard/mouse input — it lands in whatever window happens to have focus, not the app (`verify-phase.md §3b`).
 
 ## Project basics
@@ -41,7 +41,6 @@ never silently worked around.
 
 ## Slash-command syntax (READ ME if a `/agent *command` invocation fails)
 
-**Codex:** use repository skills such as `$techieflow-build`, `$techieflow-verify`, and `$techieflow-refresh-status`, or ask for the skill by name in plain language. Skills load the canonical `.tfcore/tasks/*.md` workflow. When a task calls for fan-out, delegate to the registered `tf_builder`, `tf_test_writer`, `tf_explorer`, `trblazeui`, or `techierag` Codex role and wait for its result. Defining a role alone does not authorize delegation; the user request or applicable skill must call for it. Project config and hooks require repository trust; review changed hooks with `/hooks`.
 
 **Claude Code** registers TechieFlow-native agents under the path-derived namespace `TechieFlow:agents:<name>`. The short `/<agent>` form does NOT always resolve. When in doubt use the full form:
 

package/.tfcore/templates/v4custom/app-architecture-tmpl.md

@@ -1,127 +1,119 @@
-# {AppName} — Architecture
-
-**Last updated:** {YYYY-MM-DD}
-**Status:** Current (brownfield) | Target (greenfield) | Current + planned target (brownfield with structural change)
-
-<!-- AGENT-ONLY AUTHORING NOTES. Everything in this comment is an instruction to the DRAFTING
-     AGENT, not content for the document's human reader. Carry it into the generated document
-     ONLY as this HTML comment (or drop it entirely) — NEVER as visible text: the owner reads
-     the rendered HTML and must not see authoring instructions (generate-html.md strips any
-     that leaked from older templates).
-
-  DEPTH MANDATE: this is a HUMAN document, read as rendered HTML. Module rows in §4 with
-  non-trivial behavior get a prose paragraph beneath the table, and every significant runtime
-  flow beyond §3's primary path (background jobs, ingestion pipelines, auth handshakes,
-  external-API round-trips) gets its own sequenceDiagram/flowchart. When harvesting source
-  docs, preserve their architecture content — superset, never summary.
-
-  MERMAID MANDATE: every diagram MUST follow the authoring rules in
-  .tfcore/templates/v4custom/html-render-shell.md §5.5 — quote every node/edge/subgraph label
-  (API["ASP.NET API (v2)"], not API[ASP.NET API (v2)]) and never use `end` as a node id.
-  Unquoted special characters ( ( ) / & : , … ) in flowchart labels are the #1 cause of
-  "Syntax error" diagrams in the rendered HTML.
+<!-- tf-schema
+doc: architecture
+file: docs/{App}-Architecture.md
+header: App, Kind, Size, Stack answer set, Date
+section: Stack decisions | required
+section: Solution structure | required
+section: Component map | required
+section: Data model | required
+section: Cross-cutting | required
+section: Decisions log | required
+section: Module responsibilities | optional-small
+section: Open questions | optional
+rule: stack-rows
+rule: head-project
+budget: S 2500 3500 | M 4000 6000 | L 4000 6000
+rule: stack-table
+rule: solution-table
+rule: request-flow
+rule: er-diagram
+rule: decisions-log
 -->
+<!-- Authoring notes (agent only; never visible text).
+     Sections and order are fixed by the schema above. The Stack decisions table answers the stack
+     questions (.tfcore/templates/stack-questions.md); answers taken from an answer set cite it.
+     No Deployment section: hosting is decided after UAT and lives in the Deployment Checklist; how a
+     developer runs the app lives in the UsageGuide. Detailed per-screen flows live in the DevGuide.
+     A brownfield project describes the code as it is; a planned change is a Decisions log row with
+     Status "planned" naming the BRD item that drives it.
+     Mermaid: quote every label; never use `end` as a node id. -->
+
+# {App} — Architecture
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small, Medium or Large |
+| Stack answer set | {name, or "none"} |
+| Date | {YYYY-MM-DD} |
+
+## 1. Stack decisions
+
+One row per stack question. "Source" says where the answer came from: the answer set, the owner, or the existing code.
+
+| Q | Topic | Decision | Source |
+|---|---|---|---|
+| Q1 | Configuration | {…} | {answer set / owner / code} |
+| Q2 | Secrets in development | {…} | {…} |
+| Q3 | Database | {…} | {…} |
+| Q4 | Authentication | {…} | {…} |
+| Q5 | Logging | {…} | {…} |
+| Q6 | Tests | {…} | {…} |
+| Q7 | Layout and naming | {…} | {…} |
+| Q8 | User interface | {…} | {…} |
+| Q11 | Standing rules | {…} | {…} |
+
+## 2. Solution structure
+
+| Project | Kind | Purpose |
+|---|---|---|
+| `{App}` | {web app, desktop app, API, …} | {the primary head} |
+| `{App}.Core` | class library | {…} |
+| `{App}Db` | migrations project | {…} |
+| `{App}.Tests` | test project | {…} |
+
+## 3. Component map
 
-## Table of Contents
-
-<!-- Auto-maintained by the analyst/day-1 tasks. Use the slug rule from .tfcore/templates/v4custom/html-render-shell.md §1 so links work in both MD and rendered HTML. Update this list whenever you add/rename a section. -->
-
-1. [Tech stack](#tech-stack)
-2. [Component map](#component-map)
-3. [Data flow — primary path](#data-flow-primary-path)
-4. [Module responsibilities](#module-responsibilities)
-5. [Cross-cutting concerns](#cross-cutting-concerns)
-6. [Deployment architecture](#deployment-architecture)
-7. [Architectural decisions (ADR-style log)](#architectural-decisions-adr-style-log)
-8. [Target architecture (brownfield only — if enhancement changes structure)](#target-architecture-brownfield-only-if-enhancement-changes-structure)
-9. [Open questions / risks](#open-questions-risks)
-
-## 1. Tech stack
-| Layer | Choice | Version | Notes |
-|-------|--------|---------|-------|
-| Runtime | .NET 9 | … | … |
-| UI | Blazor [Server/WASM/Auto] + TrBlazeUI | … | … |
-| AI/RAG | TechieRag | … | If applicable |
-| DB | SQL Server / SQLite / Postgres | … | … |
-| Vector store | SqliteVec / PgVector / Qdrant | … | If RAG |
-| Auth | … | … | … |
-
-## 2. Component map
 ```mermaid
 flowchart TB
-  subgraph UI["Blazor UI"]
-    Dash["Dashboard"]
-    Settings["Settings"]
-  end
-  subgraph BE["Backend"]
-    API["API"]
-    Auth["Auth"]
-    Rag["RAG service"]
-  end
-  subgraph Data["Data"]
-    SQL[("SQL")]
-    Vec[("Vector")]
-  end
-  UI --> API
-  API --> Auth
-  API --> Rag
-  Rag --> Vec
-  API --> SQL
+  UI["UI"] --> Svc["Services"]
+  Svc --> Data["Data access"]
+  Data --> DB[("Database")]
 ```
 
-## 3. Data flow — primary path
-```mermaid
-sequenceDiagram
-  actor U
-  participant UI
-  participant API
-  participant Svc as Service
-  participant DB
-  U->>UI: action
-  UI->>API: HTTPS
-  API->>Svc: call
-  Svc->>DB: query
-  DB-->>Svc: rows
-  Svc-->>API: dto
-  API-->>UI: json
-  UI-->>U: render
-```
+**How a request travels** (one typical request, in words; per-screen detail is in the DevGuide):
+1. {The page calls …}
+2. {The service …}
+3. {The data access …}
+4. {The result is shown …}
+
+## 4. Data model
 
-## 4. Module responsibilities
-| Module | Responsibility | Depends on |
-|--------|----------------|------------|
-| `src/{AppName}.Web` | UI host | Domain, Infra |
-| `src/{AppName}.Domain` | Entities, business rules | (none) |
-| `src/{AppName}.Infrastructure` | EF, external services | Domain |
-| `src/{AppName}.Rag` | TechieRag wiring (if applicable) | Domain |
-
-## 5. Cross-cutting concerns
-- Logging — Serilog file-based logging (rolling file sink under `logs/`, wired at startup in EVERY executable head — web, API, MAUI, desktop, console; app code logs via `ILogger<T>`). This is a TechieFlow standing requirement, not a per-app choice — see Coding Standards §Logging.
-- Error handling — global middleware; ProblemDetails responses
-- Auth — JWT / cookie / Azure AD
-- Caching — IMemoryCache / Redis
-- Telemetry — OpenTelemetry / Application Insights
-
-## 6. Deployment architecture
 ```mermaid
-flowchart LR
-  Dev["Dev"] --> CI["GitHub Actions"]
-  CI --> Reg["Container Reg"]
-  Reg --> AKS["Azure App Service / AKS"]
-  AKS --> ProdDB[("SQL")]
+erDiagram
+  USER ||--o{ ENTRY : writes
+  ENTRY {
+    int EntryId PK
+    string Title
+  }
 ```
 
-## 7. Architectural decisions (ADR-style log)
-- **ADR-001 — <decision>.** Reason: …
-- **ADR-002 — <decision>.** Reason: …
+| Entity | Key fields | Notes |
+|---|---|---|
+| {Entity} | {…} | {…} |
 
-## 8. Target architecture (brownfield only — if enhancement changes structure)
-```mermaid
-flowchart TB
-  Existing["existing module"] --> New["new / changed module"]
-  New --> Removed["removed box (struck through in prose)"]
-```
-Describe deltas: what's added, what's removed, what's renamed, migration path.
+## 5. Cross-cutting
+
+- **Identity:** {AppManager API, or the mechanism chosen at Q4}.
+- **Configuration:** {…}
+- **Logging:** {…}
+- **Errors:** {…}
+
+## 6. Decisions log
+
+One row per decision. Every package added to the project has a row saying why.
+
+| Date | Decision | Why | Status |
+|---|---|---|---|
+| {YYYY-MM-DD} | {…} | {…} | decided, planned, done |
+
+## 7. Module responsibilities
+
+| Module | Responsibility | Depends on |
+|---|---|---|
+| {…} | {…} | {…} |
+
+## 8. Open questions
 
-## 9. Open questions / risks
-- …
+- {…}