@naswerks/engineering-loop 0.1.0

package/templates/docs/patterns/frontend-patterns.md

@@ -0,0 +1,92 @@
+# Frontend Patterns
+
+> Rules and conventions for the client side of this repository. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — a frontend framework config (angular.json, next.config.*, vite.config.*, nuxt.config.*,
+     svelte.config.*, a React/Vue dependency), the app roots.
+     fill — two to four sentences: what the client side is, the framework, and the claim "every client
+     feature follows these conventions; read this before writing any client code."
+     absent — "No frontend detected — fill this in when a client-side stack appears. This file exists so
+     the reading floor resolves; a seat with a frontend role has nothing to read here yet." -->
+
+## Stack
+
+<!-- init: scan — framework + version, state library, data-fetching client, realtime client, styling
+     library, auth library — from the manifest with versions.
+     fill — one bullet per item: name, version, role.
+     absent — "No frontend dependencies detected — fill this in." -->
+
+## Architecture rules
+
+<!-- init: scan — tsconfig strictness, lint config rules, a framework's recommended conventions the repo
+     has pinned (standalone components, a change-detection strategy, hooks rules).
+     fill — the table `Rule | Pattern | Legacy (never use)` — the modern form the repo uses beside the
+     form it forbids, each row from a real config or an existing component.
+     absent — "No architecture rules found written down — fill this in: the component/module model, the
+     change-detection or rendering model, the DI or hook conventions, each with its forbidden legacy." -->
+
+| Rule | Pattern | Legacy (never use) |
+|------|---------|-------------------|
+
+## Component architecture
+
+<!-- init: scan — one feature folder in the client app; the kinds of component it holds.
+     fill — the kinds table (`Type | Store access | Location | Role`) and an ASCII tree of one REAL feature.
+     absent — "No component folders detected — fill this in: the component kinds and where each lives." -->
+
+## Component files
+
+<!-- init: scan — how existing components lay out their template, styles and spec (inline vs separate
+     files; the file naming).
+     fill — the rule as this repo practises it (e.g. "template and styles are separate files beside the
+     component, named {component}.component.{html,css}; a spec sits beside them"), citing two existing
+     components. This is the rule a coordinator enforces at every seat's commit.
+     absent — "No component-file convention detected — fill this in: whether templates and styles are
+     inline or separate files, and how they are named." -->
+
+## State
+
+<!-- init: scan — the state library, one store folder.
+     fill — the store convention in one paragraph and a pointer to `patterns/state-management.md` when
+     that doc exists (Snapshot — the authority is state-management.md).
+     absent — "No state library detected — fill this in: how client state is held and shared." -->
+
+## Styling
+
+<!-- init: scan — the styling library, a tokens/theme file, a global stylesheet.
+     fill — the approach in three bullets (utility-first / component CSS / tokens), the one rule for
+     component-scoped CSS, and a pointer to `patterns/ui-style-guide.md` when it exists.
+     absent — "No styling library detected — fill this in: how components are styled and themed." -->
+
+## Realtime
+
+<!-- init: scan — a realtime client (signalr, socket.io, ws, sse, pusher, ably).
+     fill — one paragraph: how server events reach the client and the poke/refetch rule; a pointer to
+     `infrastructure/realtime-events.md` when it exists.
+     absent — "No realtime client detected — the client reads on navigation and on user action only;
+     fill this in when a realtime channel appears." -->
+
+## Codegen pointer
+
+<!-- init: scan — a generated/ folder inside the client app, a codegen config.
+     fill — "Never hand-write or edit files in `{generated folder}` — they are produced by {tool} and
+     overwritten on the next run. Everything else is the authority of `patterns/codegen.md`."
+     absent — "No generated client code detected — fill this in when a codegen pipeline appears." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+<!-- init: scan — the app config/composition root, the router, the shared components folder, the global
+     stylesheet, the constants file.
+     fill — one row per file, verbatim path.
+     absent — "| (none detected) | fill this in: the app config, the routes, the shared components |" -->
+
+## Lineage
+- **Related** — [vertical-slice-anatomy](vertical-slice-anatomy.md) · [testing](testing.md) · [codegen](codegen.md) · [backend-patterns](backend-patterns.md)

package/templates/docs/patterns/state-management.md

@@ -0,0 +1,73 @@
+# State Management
+
+> The store convention for the client side of this repository: the files per store, how a store is
+> registered, how a component consumes it. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Structure
+
+<!-- init: scan — the state library (from the manifest) and ONE existing store folder.
+     fill — the library and version, then an ASCII tree of one REAL store with a comment per file, and the
+     rule for sub-stores if the repo has them.
+     absent — this doc is only drafted when a state library is found; if you are reading a draft with this
+     line, the scan found the library but no store folder: "No store folder detected — fill this in: the
+     files a store is made of." -->
+
+```
+{feature}/store/
+  ...
+```
+
+## Actions / events
+
+<!-- init: fill — how actions are declared and named (the naming convention read off the existing store,
+     e.g. `[Feature] Verb Noun`), with a real example.
+     absent — "No action convention detected — fill this in." -->
+
+## Model
+
+<!-- init: fill — where the state types come from (derived from generated types? hand-written?), with a
+     real example.
+     absent — "No model convention detected — fill this in." -->
+
+## Data access
+
+<!-- init: fill — the file that talks to the server on the store's behalf, and the rule that components
+     never call it directly, with a real example.
+     absent — "No data-access convention detected — fill this in." -->
+
+## State class / reducer
+
+<!-- init: fill — selectors, handlers, error handling, the realtime-event handlers if any, with a real
+     example. -->
+
+## Registration
+
+<!-- init: scan — where stores are registered (app config, root module, a provider list).
+     fill — the exact file and the one line to add.
+     absent — "No registration point detected — fill this in." -->
+
+## Component consumption
+
+<!-- init: fill — how a component reads (a selector, a signal, a hook) and writes (dispatch), with a real
+     example. -->
+
+## Rules
+
+<!-- init: scan — lint rules or CONTRIBUTING notes about state.
+     fill — bold-lead imperative bullets, each citing its source when written down; the loop supplies one:
+     "**Keep high-frequency streams OUT of the store** — a byte/token stream belongs in a plain service the
+     component subscribes to; only low-frequency control events go through the store."
+     absent — the one loop-supplied bullet, then "- No further store rules found written down — fill this
+     in." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+
+## Lineage
+- **Related** — [frontend-patterns](frontend-patterns.md) · [vertical-slice-anatomy](vertical-slice-anatomy.md)

package/templates/docs/patterns/testing.md

@@ -0,0 +1,103 @@
+# Testing Patterns
+
+> How to write and run tests in this repository — every lane. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — the test frameworks in the dependency manifests and the CI jobs that run tests.
+     fill — two to four sentences: which kinds of test carry the weight here (unit / integration / e2e),
+     against what (real database, real HTTP, fakes), ending with the claim "every feature follows these
+     conventions; read this before writing any test."
+     absent — "No test framework detected — fill this in: what kinds of test this repository relies on,
+     and against what boundaries." -->
+
+## Stack
+
+<!-- init: scan — every test-related dependency with its version (vitest, jest, mocha, xunit, nunit,
+     pytest, go test, cargo test, playwright, cypress, testcontainers, wiremock, msw …).
+     fill — one bullet per tool: name, version, what it is for.
+     absent — "No test framework detected — fill this in: the runner, the assertion library, the fakes." -->
+
+## Running tests
+
+<!-- init: scan — package.json scripts, Makefile/justfile targets, *.sln/*.csproj test projects, CI
+     workflow steps; the app roots (one lane per app or project).
+     fill — ONE fenced block per lane: the exact command, the working directory it runs from, and a
+     comment saying what a green run prints (the summary line). Commands verbatim from the scan, never
+     paraphrased.
+     absent — "No test command detected — fill this in: the exact invocation per lane, from the
+     directory it runs in, and what a green run prints." -->
+
+```
+# lane: {name} — from {directory}
+{the exact command}                      # green prints: {the summary line}
+```
+
+## The run protocol
+
+Follow this before trusting any red OR green:
+
+- **Suites run SERIALLY, never concurrently** — concurrent runners flake, and a failure seen only in a
+  concurrent run is rerun standalone before it is investigated.
+- **Capture the full runner output to a UTF-8 file and search failure names** — a "last N lines" filter
+  destroys the names; a run whose output file is empty proved nothing.
+- **Read the summary block, never the exit code alone** — a run that printed no totals ran nothing,
+  whatever its exit code said; a green exit is a claim, not a receipt. Implausible speed is a failure
+  signal.
+- **Disclose every red run WITH its rerun** — never present a flake as clean.
+- **A number without its invocation is not a receipt** — quote what ran, from where, and the scope.
+
+<!-- init: scan — FLAKY-TESTS.md, a "known flaky" list in CONTRIBUTING.md, CI retry configuration.
+     fill — a "Known flaky tests" list by name, with the reason and what to do (rerun once; stop on two).
+     absent — leave the five bullets above as they are; add nothing. -->
+
+## What to test where
+
+<!-- init: scan — the folder layout (Features/, apps/*, packages/*), existing test folders and their
+     naming, one existing test file per kind as the example.
+     fill — one bullet per slice kind ("a sync endpoint: …", "a repository: …", "a store: …", "a pure
+     service: …"), each naming an existing test file as its reference. Plus the test-naming convention
+     read off the existing tests (plain-English behavioural sentences, or the repo's own).
+     absent — "No test folders detected — fill this in: what each kind of code is tested with, and one
+     reference test per kind." -->
+
+## Controls — a pin must be able to fail
+
+A test that cannot go red is a green light with a test's name on it. For every probe, pin or scanner:
+
+- **Name its positive control** — the case that MUST go red — and state what would make it fail.
+- **The pair must disagree.** One variable changes between the subject and its control; if the same
+  input produces the same verdict on both sides, you have one observation wearing two names.
+- **Prove it once:** break the thing on purpose, watch the control go red, fix it, watch it go green,
+  and quote both runs. A control asserted is a control assumed.
+- **Pin the PROPERTY, not the wording.** Assert the behaviour in the assertion's own message; source
+  any literal you must name from the producer's own constant, and assert that constant is non-empty.
+
+<!-- init: scan — an existing test that pairs a subject with its own control (a "CONTROL" or "inverted"
+     case), if one exists.
+     fill — name that test as the shape to copy.
+     absent — leave the four bullets; add "No paired control found in the existing tests — fill this in:
+     the first pin that carries its own control becomes the reference here." -->
+
+## Coverage
+
+<!-- init: scan — coverage configuration (a floor file, a threshold in the runner config, a CI gate).
+     fill — the floor, the command that measures it, and the gate that enforces it.
+     absent — "No coverage gate detected — fill this in: whether coverage is measured, the floor, and
+     the gate." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+<!-- init: scan — every file the sections above named (runner configs, shared fixtures, CI workflows,
+     the flaky list).
+     fill — one row per file, verbatim path.
+     absent — "| (none detected) | fill this in: the runner config, the shared fixtures, the CI workflow |" -->
+
+## Lineage
+- **Related** — [backend-patterns](backend-patterns.md) · [frontend-patterns](frontend-patterns.md) · [vertical-slice-anatomy](vertical-slice-anatomy.md)

package/templates/docs/patterns/ui-style-guide.md

@@ -0,0 +1,76 @@
+# UI Style Guide
+
+> Which class or component to reach for, for which job, and the composition rules that keep screens
+> consistent — plus the design tokens and how to consume them. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## The mental model
+
+Every element on screen falls into one of these roles. Name the role before you pick a class.
+
+| Role | What it is | Visual weight | Example |
+|------|-----------|---------------|---------|
+| **Primary action** | the thing you WANT the user to do | highest — filled, coloured | Create, Send, Save |
+| **Secondary action** | useful but not the main goal | medium — outlined | View, Details, Refresh |
+| **Passive action** | navigation away, undo, dismiss | lowest — ghost / minimal | Back, Cancel, Close |
+| **Destructive action** | permanent data loss | high, danger-coloured | Delete, Remove |
+| **User content** | text the user wrote or data they own | emphasised | names, values, messages |
+| **System content** | app-generated text, metadata | neutral, de-emphasised | helper text, timestamps |
+| **Status indicator** | communicates state without action | colour-coded by meaning | badges, alerts |
+| **Navigation** | moves between pages | subtle until hovered | breadcrumbs, tabs, sidebar |
+| **Metadata** | labels, counts, ids | minimal, neutral outline | pagination, "Showing X of Y" |
+
+## Action hierarchy
+
+**One primary action per context** (page header, card, modal, form). Everything else is secondary or
+passive.
+
+<!-- init: scan — the UI library (tailwind, daisyui, mui, chakra, bootstrap, shadcn …) and two existing
+     pages/components (a header with actions, a form footer).
+     fill — the button decision tree in this repo's class names, then "Current patterns": a fenced
+     snippet each for a page header, card actions, a modal footer, a form bottom, copied from real files.
+     absent — "No UI library detected — fill this in: the class or component for each role above." -->
+
+## Content roles
+
+<!-- init: fill — three tables (`Element | Style | Why`) for user content, system content, and status
+     indicators (positive / warning / error / info / neutral / category), in this repo's classes.
+     absent — "No content-role classes detected — fill this in." -->
+
+## Page layout and page states
+
+Every data-driven page handles four states: **loading**, **error**, **empty**, **content**.
+
+<!-- init: scan — a shared page-header / empty-state / loading / error component, if any.
+     fill — the standard page skeleton (an ASCII box), the shared components to use for the four states,
+     and the state-switch idiom the repo uses.
+     absent — "No shared page components detected — fill this in: the page skeleton and the four-state
+     components." -->
+
+## Tokens
+
+<!-- init: scan — a tokens/theme file, a global stylesheet, the UI library's token variables.
+     fill — a table `Token | CSS variable | Purpose | When to use` for brand, base and status tokens,
+     then the ONE consumption rule for component CSS (use `var(--…)` tokens, never a literal colour; how to
+     express opacity), and the dead forms to grep for if the library moved majors.
+     absent — "No design tokens detected — fill this in: the colour and spacing tokens and how component
+     CSS consumes them." -->
+
+## Forms
+
+<!-- init: fill — the field pattern, input states, validation display, in this repo's classes.
+     absent — "No form convention detected — fill this in." -->
+
+## Quick reference: element to style
+
+<!-- init: fill — a two-column table `Element | Style` compiled from the sections above.
+     absent — "Compile this table once the sections above are filled." -->
+
+| Element | Style |
+|---------|-------|
+
+## Lineage
+- **Related** — [frontend-patterns](frontend-patterns.md)

package/templates/docs/patterns/vertical-slice-anatomy.md

@@ -0,0 +1,61 @@
+# Vertical Slice Anatomy
+
+> Where to place each piece when building a feature in this repository. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Feature structure
+
+<!-- init: scan — the folder layout two deep for every stack (Features/, src/app/, apps/*, packages/*,
+     cmd/, internal/, lib/), and ONE existing feature per stack.
+     fill — one ASCII tree per stack showing a REAL feature as it exists, side by side when there are
+     two, with a comment per folder saying what goes there; then one sentence per stack on what lives
+     OUTSIDE a feature (shared infrastructure, cross-cutting stores).
+     absent — "No feature layout detected — fill this in: where a feature's files go, per stack, as a
+     tree copied from a real one." -->
+
+```
+{stack A}                                 {stack B, if any}
+{root}/{Feature}/                         {root}/{feature}/
+  ...                                       ...
+```
+
+## The kinds of file, and their roles
+
+<!-- init: scan — the kinds the trees above show (endpoint / model / query / service; page / component /
+     store; command / handler).
+     fill — a table `Kind | Role | Where | Owns` with one row per kind.
+     absent — "No kinds detected — fill this in: each kind of file a feature holds, and what it owns." -->
+
+| Kind | Role | Where | Owns |
+|------|------|-------|------|
+
+## Checklist: new feature
+
+<!-- init: scan — the trees above, the registration points (composition root, router, module list), the
+     test conventions in patterns/testing.md § What to test where.
+     fill — an ordered `- [ ]` checklist per stack: create X in {path} (one line on what it must extend
+     or implement), register it in {file}, add the route/handler in {file}, add the tests the testing doc
+     names for each kind, run the build. Each item is a real path.
+     absent — "- [ ] No feature layout detected — fill this in: the ordered steps that add a feature,
+     each naming its file." -->
+
+### {stack A}
+
+- [ ]
+
+### {stack B}
+
+- [ ]
+
+## Gotchas
+
+<!-- init: scan — CONTRIBUTING.md, CLAUDE.md, AGENTS.md, lint rules that fire on layout (import
+     boundaries, dependency-cruiser, ArchUnit-style rules).
+     fill — one `### Gotcha:` per written-down layout rule, citing its source file.
+     absent — "No layout gotchas written down yet — fill this in the first time one bites." -->
+
+## Lineage
+- **Related** — [backend-patterns](backend-patterns.md) · [frontend-patterns](frontend-patterns.md) · [testing](testing.md)

package/templates/docs/readme-archive.md

@@ -0,0 +1,9 @@
+# archive/
+
+Completed or abandoned efforts, grouped into topic folders. Write-once: frozen history, never edited — a
+stale reference in an archived doc is the record of what was believed at the time. A spec-driven effort
+archives in the split shape (`project-status.md` at the root, `specs/`, `implementation/`,
+`sessions/`); a small effort is flat. `archive/audit/` is the one exception to topic grouping: audit
+reports sit beside the living docs they audit, and the cross-cutting health report sits at its root.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-features.md

@@ -0,0 +1,7 @@
+# features/
+
+What exists — one doc per feature. Descriptive: born from `docs-process` after code ships, verified
+against the code, and audited by `docs-audit-feature` (folder mode also flags code with no doc). The
+folder IS the feature inventory; there is no separate catalogue.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-guides.md

@@ -0,0 +1,7 @@
+# guides/
+
+How to ADD a new thing — step-by-step walkthroughs (a new service, a new app, a new worker). Prescriptive:
+the guide is the decided way, and code conforms to it. Patched by `docs-process` when a session changes
+the way; audited by `docs-audit-feature` for whether the code still follows it.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-infrastructure.md

@@ -0,0 +1,7 @@
+# infrastructure/
+
+What runs under the hood — the technologies and plumbing. Descriptive: the code is truth, and these docs
+are verified against source (`docs-audit-feature` fixes the doc to match the code). Born from
+`docs-process` after something ships, or drafted by `init` from a scan and marked `status=draft`.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-patterns.md

@@ -0,0 +1,9 @@
+# patterns/
+
+Conventions to FOLLOW when writing code. Prescriptive: truth is by decision, so a mismatch between a
+pattern doc and the code is usually a code problem to flag, not a doc to rewrite. Every seat reads the
+floor (`vertical-slice-anatomy`, `backend-patterns`, `frontend-patterns`, `testing`, `codegen`)
+before it writes a line; a doc marked `status=draft` was scanned by `init`, not decided — promote it as
+you confirm each section.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-research.md

@@ -0,0 +1,9 @@
+# research/
+
+The running tab of ideas not yet built. `docs-backlog` creates a research doc here; a spec pipeline lives
+in `research/{topic}/` (an ignition brief, an umbrella, one numbered spec per session, the tracker, the
+live-checks). A research doc stays here through the build — however many sessions and working docs that
+takes — and is archived WITH its working docs by `docs-process` when the effort finishes. The folder is
+the queue; nothing here is done.
+
+A README in this folder is never a queue entry.

package/templates/docs/readme-working.md

@@ -0,0 +1,9 @@
+# working/
+
+Per-session handoff docs. `docs-write` finishes one at the end of every build session and leaves it here;
+one effort may chain several (each `Builds on` the last, all with the same `Source:`). They leave only
+through `docs-process`, which patches the living docs from their **Living Docs to Update** checklists and
+then files the whole effort into `archive/{topic}/`. The folder is a shared queue: other efforts' docs may
+sit beside yours, and membership is never inferred from the folder.
+
+A README in this folder is never a queue entry.

package/templates/settings-pin.json

@@ -0,0 +1,10 @@
+{
+  "extraKnownMarketplaces": {
+    "engineering-loop": {
+      "source": { "source": "github", "repo": "naswerks/engineering-loop" }
+    }
+  },
+  "enabledPlugins": {
+    "naswerks@engineering-loop": true
+  }
+}