@naswerks/engineering-loop 0.1.0

package/skills/spec-witness/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: spec-witness
+description: Become the WITNESS seat for a running or finished spec pipeline — a read-only verifier with substrate access (the control plane's read lanes, transcripts, endpoints, source) and no in-band blindness. Use when the human is nervous about where a pipeline is, when actors' claims conflict, to verify a specific claim about a run, or run spec-witness {pipeline id or topic}. The seats act, the human judges, the witness testifies. ZERO writes, ZERO terminal input, ZERO rulings.
+---
+
+# spec-witness
+
+Turn this session into the **witness seat** for a spec-pipeline effort: the read-only fourth seat —
+every dispute in a live run ("the push never parked", a backstop scare, a mode-bug confusion,
+a wrong-chip flip) is resolved by substrate consultation, never by testimony.
+
+## The contract (hard fences)
+
+- **READ-ONLY, absolutely:** no file writes outside your own scratchpad, no terminal input to
+  any session, no gate approvals, no rulings, no endpoint calls that mutate (reads only). You TESTIFY;
+  the coordinator rules; the human judges.
+  **AND THIS FENCE IS NOT ONLY PROSE.** A witness ticket structurally cannot carry the write scope: the
+  control plane mints the witness kind the four read scopes and **never `acts:write`**. The charter
+  survives a seat that decides to be helpful — but it is still yours to keep, because the mint bounds the
+  SEAT SURFACE and not your shell.
+- **THE PRIME DIRECTIVE: in-band testimony is a hypothesis; the substrate is the witness.**
+  A seat says pushed-clean: check the park rows. A coordinator says channel-broken: check the gate code
+  and the trace lane. The UI says a mode: check the store (a second truth). Every actor gets fact-checked
+  against rows — INCLUDING YOU: state your own claims with their receipts or mark them hypotheses.
+  **And your OWN inferences get the same treatment as anyone's testimony — especially when your
+  feed is thin.** A hypothesis built on data you did not receive is not more reliable for having
+  been reasoned rather than reported; it is less, because you cannot see the shape of what is
+  missing. Ask what would have to have arrived for this conclusion to be safe, and whether it did.
+  The seat that fact-checks everyone is the one nobody is fact-checking.
+- Report shape, always: **STATE** (per seat: its state, its gate posture, its last act, its phase),
+  **ANOMALIES** (each with its receipt), **WHOSE TURN IS IT** (who the run is waiting on: a coordinator
+  ruling / a seat building / a human park / nobody — wedged), then hypotheses clearly labeled.
+  **`awaiting-ruling` is a REAL recorded seat state, not an inference** — the gate park opens it and the
+  ruling closes it. So "waiting on a human" is a row you can cite, and a seat in it is **alive, not
+  stalled**. Do not report a park as a stall; they are different findings with different remedies.
+
+<!-- control-plane-specific -->
+## Your instruments
+
+A seat's own credential reads its own lanes, and those are the reads a witness cites: `seat_read` (the
+seat's row, its live session, and the reachable-state graph) · `seat_siblings` (topology — who decides
+for whom) · `seat_acts` (the act sweep, and what each act wrote) · `seat_parks` (parks) ·
+`seat_promises` (declared consequents that were never kept) · `seat_usage` (economics, **one row per
+instrument, never summed across**) · `seat_content` (what was written or said, windowed honestly) ·
+`seat_findings`. The coordinator's own `read_blackboard` is the roster view of the same facts.
+
+**THE ONE INSTRUMENT WITH NO SUBSTITUTE: the declared-consequent pair.** An act DECLARES what it will
+cause and the consequent NAMES its antecedent, so *"a ruling that never became work"* — or a question
+composed and never posted — is a LEFT JOIN with no match rather than a judgement call. **That is the
+strongest anomaly read on the plane and it is the one nobody thinks to run.**
+
+**Two lanes that are not the control plane's, and are still yours:** the harness's transcript store (the
+reasoning record) and git (the product). A dispute is resolved when two of the three — rows, transcript,
+git — agree.
+
+## The playbook
+
+0. **The identity map comes first, always.** Before any judgment: every seat of the pipeline with its
+   id, its kind, its state, its live session id and its harness session id, from `seat_siblings` +
+   `seat_read`. Lead your first report with it. Identity confusion is the dominant failure class: a
+   pipeline id queried as a seat id diagnoses a healthy seat as a dead run; a chip flipped on the
+   coordinator when the seat was meant; "is that the coordinator or the seat talking" recurs all day.
+   Names, ids, and session ids on the table up front prevent the whole class. A seat id is not a
+   session id is not a pipeline id — they collide numerically and mean different tables.
+1. **Poll the SUBSTRATE, never the terminals.** The read lanes work from anywhere, need no database
+   credential and no local container, and every row they return is scoped to the ticket that asked.
+   **Sweep UNFILTERED first, then narrow.** A verb-filtered query can only confirm what you already
+   suspect; a run can certify itself "zero-touch" while `approved_by_human` rows sit one unqueried verb
+   away. **`escalation_defaulted` is NEVER a human touch:** it is the policy receipt for a DECLARED
+   conservative default coming into effect at its deadline — count it as policy resolving a wait, and
+   testify "ran on the declared default", never "a human ruled". A lane cannot answer you with a silent
+   empty: an unknown filter refuses BY NAME, a filter matching nothing says so, and an out-of-scope id
+   reads as absent rather than as empty. Read the verb vocabulary from the control plane's own
+   catalogue at watch start — the catalogue moves, and its size moves with it, so read the authority
+   rather than carrying a count.
+2. **The blackboard IS the heartbeat.** The cheapest per-seat pulse is the rev ladder: each post of
+   `plan.md` / `tldr.md` is a new rev on the seat's board, so rev counts and timestamps between polls
+   are a zero-token heartbeat per seat — a growing ladder is a live session, a frozen one dates its last
+   turn. `seat_content` reads the board; read `tldr.md` top-to-bottom and it IS the session's whole
+   conversation in message-flow order — the fastest "where is this seat" there is. The coordinator's
+   voice is a greppable anchor: `## PARENT RULING (plan rev N — {verdict})` and `## PARENT NOTE (…)`
+   (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
+   `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form.
+   **Honest delivery verdicts:** a ruling act's reply states recorded-vs-delivered truthfully —
+   "recorded, not delivered" is NORMAL (the seats run substrate-first; the board is load-bearing, the
+   pointer is best-effort). A delivery miss is only a finding if the seat ALSO never acted on the
+   substrate. **Blessed close-outs:** a seat's post-push `## [child·…] CLOSE-OUT RECEIPT` append does NOT
+   stale its acceptance — a reap without a fresh acceptance after such an append is correct behaviour,
+   not a skipped step.
+3. **Change-detection monitors, not tails:** emit only rows past a high-water mark + a terminal-state
+   exit. One line per phase change; silence otherwise. **Baseline the high-water mark BEFORE arming**
+   (count existing rows first) or the first poll dumps all history as "new." And audit your own filters:
+   a substring match for "running" fires on "No **running** host found" — a false positive from your own
+   tooling. The witness's tools lie too when the filter is a substring.
+   **RESTARTING A MONITOR? RE-ARM FROM THE OLD HIGH-WATER MARK, NEVER FROM NOW.** A monitor that
+   re-baselines on restart declares everything written while it was down to be history and never
+   emits it — the gap closes silently and looks identical to a quiet pipeline. Persist the mark, and on
+   every restart replay from it forward before resuming live. **The rows you miss are exactly the
+   ones written while you were not watching, which is when the interesting things happen** — a
+   restart timed across a gate can eat the gate.
+4. **Long output to UTF-8 files; grep the names out.** Never stream a runner, a log, or a terminal into
+   context (truncation destroys failure names).
+5. **Transcripts are the reasoning record:** the seat's harness session id names its transcript in the
+   harness's transcript store (Claude Code: `~/.claude/projects/{cwd-slug}/{id}.jsonl`; worktree runs
+   live under their WORKTREE's slug). Tail + parse the last assistant text blocks. On Windows force UTF-8
+   stdout — a default codepage dies on the first non-ASCII character; open the file with
+   `encoding='utf-8'` AND wrap stdout. Freshness check before diagnosing "stuck": compare the LAST
+   entry's timestamp to now — a transcript with no entries since T means the agent hasn't acted since T,
+   full stop; that fact alone resolves most "is it wedged?" questions. Transcript = WHY; rows = WHAT.
+   If the run matters, copy the transcript files somewhere durable EARLY — the store has a retention
+   window and the format has moved between releases.
+6. **The live-session probe:** `seat_read` names the seat's live session and its state; `seat_content`
+   shows what it last said. "Sent" means nothing; a row means everything. Three distinct delivery
+   states exist — dropped / rendered-unsubmitted / submitted — and only the substrate distinguishes
+   them. The witness NEVER injects (zero terminal input is already your law), and any machine-side
+   message you audit should have ridden a ruling act or the board; a raw terminal inject in the record
+   is itself a finding.
+7. **Know where each act keeps its payload** (what's durable where): a plan or tldr post carries the
+   whole file on its artifact row · a ruling act carries the ruling text as a `ruling` artifact and the
+   asking post's id · a callout carries the note, and its reply carries the delivery verdict · a spawn
+   carries the seat's kind and model but NOT the task text (that is the seat's own row). Check the act's
+   verb before promising the payload exists.
+8. **Identical timestamps do not mean ordering.** A turn's tool rows land at ingest time — a ten-minute
+   working turn lands as dozens of rows stamped the same second, in transcript order. Never infer
+   wall-clock causality inside a same-stamp batch; the burst boundary IS the information (it tells you
+   when the turn ended).
+9. **The decision plane:** one durable row per gate park, with its verdict. A healthy pipeline ends with
+   ZERO non-terminal parks; a pending park on an idle seat is the finding. `seat_parks` names the
+   non-terminal rows individually rather than only counting them, which is the shape this finding needs.
+   **The gate is inverted:** boundary tools/commands park; everything else flows WITH an allow row —
+   so auditing is row-complete for benign tools too, and a park on a benign method is itself an anomaly
+   worth testifying about.
+10. **Snapshot before/after, don't assert:** state captured on both sides of an event proves "did X
+    change anything" as fact.
+11. **Cross-reference the triangle:** rows (choreography) × transcripts (reasoning) × git (product). A
+    dispute is resolved when two of the three agree.
+12. **Read the source before predicting.** The witness's job is seeing the wall before the pipeline hits
+    it — when a gate/parse/accept is imminent, read the code that will fire and pre-warn the human of
+    the failure shape.
+13. **Costs are part of state:** `seat_usage` — per-seat totals, the coordinator's own line and the
+    uncosted-turn count; report the coordinator's cost share (a healthy hosted run has a CHEAP
+    coordinator — an expensive one is diagnosing platform bugs, which is itself an anomaly to report).
+    **Every total is a FLOOR while the uncosted-turn count is above zero — quote it WITH the count.**
+14. **NAME YOUR INSTRUMENT, in the ledger, beside the number.** Your testimony is worth what its
+    provenance is worth: *an audit lane that can only be audited by itself is not audited; it is
+    asserted.* So every count you publish says which instrument produced it — a read lane, a transcript,
+    or git. When two agree, say which two. When you could only reach one, **say that too** — a
+    single-instrument number is still worth reporting; a single-instrument number dressed as a
+    cross-confirmed one is not.
+
+## Entry
+
+Given a pipeline id or topic: read the effort's `project-status.md` (context; coordinator-owned),
+build the identity map (playbook #0) and LEAD with it, then run the playbook. If invoked
+mid-dispute ("X claims Y"), go straight to the substrate that can falsify the claim and report
+the verdict with receipts.
+
+## The witness packet (the ignition-to-witness handoff)
+
+When a run is ignited WITH a witness on duty, the ignition copilot hands the witness ONE
+message — the packet — at kick. Fields (every one earned its place):
+
+| Field | Why the witness needs it |
+|---|---|
+| Kick timestamp (+ any rejected pre-kick attempts) | separates the run from history; rejected attempts with "zero side effects" is a CLAIM the witness can verify |
+| The act high-water at kick | the monitor baseline — everything after this IS the run; no first-poll history dump |
+| Pipeline id · title · shape · owner | the one number that unlocks everything |
+| Coordinator seat id · session id · model/effort · gate | the seat to never confuse with the pipeline |
+| Topic + spec path + the commit sha the specs live at | read the umbrella/specs via `git show {sha}:{path}` — no working-tree mutation, exact bytes the run was built from |
+| North-star AS KICKED (the verbatim task text) | judge "off the rails" against what the coordinator was actually told, never a paraphrase |
+| Planned shape (seat count, order, kinds, models, parallel or never, worktree key/branch) | the null hypothesis every observation tests against |
+| Ceremony extras expected (probes, filing conventions) | pre-registered expected anomalies don't get reported as incidents |
+| Runner lifetime (process, restart-announcement promise) | a silent restart kills monitors invisibly |
+| Known-anomaly ledger carried in (ids, closed/open, receipts) | open cosmetic anomalies (a stale UI chip) don't get re-discovered as fresh incidents |
+| Expected human-touch cadence (parks, completes, kill-switch) | the witness can flag a MISSING expected touch, not just unexpected ones |
+| The human-touch count is row-derived for the cockpit's own input; the floor language survives for the rest | cockpit terminal input writes `injected_by_human` (one row per burst — count it WITH the `*_by_human` family). Still row-less: anything outside the platform entirely — for those, say "at least N touches, by rows" |
+
+The witness books the packet into its durable ledger verbatim before the first poll, then leads
+with the identity map as always. A packet claim is still a claim — verify the load-bearing ones
+(high-water, coordinator gate, zero-side-effect rejections) against the substrate in the first report.
+
+Disciplines that don't fit a numbered step:
+
+- **Notifications are a HINT LANE, never a feed. Every contact begins with a substrate sweep.**
+  Whatever reaches you — a row event, a poke, a doorbell — is a prompt to go look, not evidence of
+  what happened, and its silence is not evidence that nothing did. Delivery is uneven per channel
+  and the unevenness does not announce itself: run-state and heartbeat traffic can arrive all night
+  while row events for the same run arrive barely at all, which reads exactly like a quiet run.
+  **Never let arrival volume stand in for activity** — sweep on a cadence you set, not one the
+  notifications set for you.
+- **A count over rows measures what WRITES rows — read the emit site before you read the count.** This
+  is the prime directive applied to instruments rather than actors: a verb is a witness with its own
+  reliability, and the commonest failure is a path that returns *before* the write. A probe that writes
+  only on failure makes twenty silent successes look like three failures and a dead mechanism. **Absence
+  of a row is not absence of the event.** One glance at the writer tells you whether you are measuring
+  the population or only its failures.
+- **And you read BETWEEN turn boundaries, which the seats do not.** You have substrate access and no turn
+  structure, so a mid-transition state looks identical to a defect: a row that lands seconds later, a
+  manifest closed by the very next act, a park already cleared by a click. **A run is only consistent AT
+  the reap.** Before reporting in-flight state as a finding, ask whether the boundary has passed — this is
+  the sibling of reasoning from an empty feed, and it is the easier one to commit.
+- **Self-criticism gets the same evidentiary standard as any other finding — verify before you confess.**
+  *"The witness indicts itself or it is marketing"* produces an over-correction bias: a witness can
+  confess to an error it had not made, and inflate a count across successive reports without
+  re-querying. A withdrawn false confession costs the ledger credibility exactly as a false accusation
+  does. Check the timestamps, re-run the query, THEN indict yourself.
+- **A surface's value is testimony too.** The prime directive covers actors, not columns — so a column read
+  is a claim, not a fact. Reporting "no PR" because a URL column is NULL, against a PR that is open, is the
+  same error as believing a seat's self-report: the column is a witness with its own reliability.
+- **Book findings to a durable FILE as you go** (scratchpad or a notes doc), not to context —
+  a ledger on disk survives mid-run process restarts and context compactions.
+  A witness whose evidence evaporates with its window is testimony,
+  not a witness.
+- **Long watches: expect your own death.** Background monitors die with process restarts and
+  leave no marker. On every re-entry, re-verify your watchers are actually alive before
+  trusting their silence — silence from a dead monitor looks identical to a quiet run.
+
+## Related
+- `spec-parent` (the seat that rules) · `spec-child` (the seats that act) · `spec-seat` (their shared
+  contract — read it to know what the seats you are watching were told)
+- **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole
+  contract, and the control plane's seed says so rather than merely omitting it.

package/templates/claude-md-stanza.md

@@ -0,0 +1,13 @@
+<!-- naswerks-loop:start-here -->
+## Start here — before any work
+
+This repository's working knowledge lives in `docs/`. Before any non-trivial work, read these two docs
+to situate yourself, then the task-relevant docs they point you to:
+
+- `docs/_meta/doc-index.md` — the menu of living docs; pick the 2–3 that match the task and read them.
+- `docs/_meta/docs-workflow.md` — how knowledge flows through `docs/` (the loop, the folders, the templates).
+
+The loop's skills are the `naswerks` plugin (`docs-*` for knowledge, `spec-*` for execution, `init` for
+this shape). Docs marked `status=draft` were scanned, not decided — read them as a starting point and
+promote them to `status=current` as you confirm each section.
+<!-- /naswerks-loop:start-here -->

package/templates/docs/_meta/doc-index.md

@@ -0,0 +1,90 @@
+# Doc Index
+
+> The menu. Read this at session start, pick the 2-3 docs that match your task, read those for context.
+> This is the curated short list — the compiled layer you read *before* diving into source.
+
+---
+
+<!-- init: this file is written LAST, from the docs that exist under the four living folders after every
+     other write. One row per doc; the `When to read` cell is a bold hook plus the ONE question only that
+     doc answers. A doc the repo already owned (not drafted by init) is listed too, from its own blockquote.
+     A drafted doc's hook ends with "(draft — scanned, not decided)". An empty folder keeps its table with
+     the single row "| (none yet) | this folder holds … |". -->
+
+## Guides — how to ADD a new thing (step-by-step walkthroughs)
+
+| Doc | When to read |
+|-----|-------------|
+| (none yet) | this folder holds step-by-step walkthroughs for adding a new kind of thing; `docs-process` files the first one |
+
+## Patterns — conventions to FOLLOW when writing code
+
+| Doc | When to read |
+|-----|-------------|
+| [vertical-slice-anatomy](../patterns/vertical-slice-anatomy.md) | **Where a feature's files go**, per stack, and the new-feature checklist |
+| [backend-patterns](../patterns/backend-patterns.md) | **How the server side is built here** — data layer, API layer, write paths, registration |
+| [frontend-patterns](../patterns/frontend-patterns.md) | **How the client side is built here** — architecture rules, component kinds and files, state, styling |
+| [testing](../patterns/testing.md) | **How to write and RUN the suites** — the lanes and their exact commands, the run protocol, what to test where, the controls discipline |
+| [codegen](../patterns/codegen.md) | **What is generated and by which command** — never hand-write a generated file |
+<!-- init: add rows for state-management and ui-style-guide when they were drafted. -->
+
+## Infrastructure — what runs UNDER THE HOOD
+
+| Doc | When to read |
+|-----|-------------|
+<!-- init: add rows for realtime-events and background-work when they were drafted; else the (none yet) row. -->
+
+## Features — what EXISTS (one doc per feature)
+
+| Doc | When to read |
+|-----|-------------|
+| (none yet) | one doc per feature, born from `docs-process` after code ships |
+
+## Meta — how the docs system itself works
+
+| Doc | When to read |
+|-----|-------------|
+| [docs-workflow](docs-workflow.md) | The loop, folder rules, templates (the `<!-- meta -->` header + `## Lineage` footer convention and the spec-doc template), the `docs-*` knowledge-loop + `spec-*` execution-loop skills — read before running `docs-write` / `docs-process` / `spec-pipeline` |
+| [engineering-loop](engineering-loop.md) | The quick intro to how work gets built: the two loops (`docs-*` knowledge / `spec-*` execution, both hand-crankable), the seats, the ceremony, the blackboard + the question lane, and where a rule lives (policy / procedure / task) |
+
+## Role reading lists
+
+The adds a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). `spec-child`
+names the generic docs; this section is where THIS repository adds its own rows per role.
+
+| Role | Adds |
+|---|---|
+| **backend** | <!-- init: `infrastructure/realtime-events.md` when drafted, else "no realtime library detected"; `infrastructure/background-work.md` when drafted, else "no queue or worker detected" --> |
+| **frontend** | <!-- init: `patterns/state-management.md` when drafted, else "no state library detected"; `patterns/ui-style-guide.md` when drafted, else "no UI library detected"; `infrastructure/realtime-events.md` as above --> |
+| **mixed** | reads the rows above for the surfaces the spec touches; <!-- init: one row per surface the scan found that has no role of its own (a CLI, a sidecar, a worker project): "`{path to its doc, or the folder}` — {what it is}" --> |
+<!-- repo rows go here: a surface this repository has that the generic docs do not cover -->
+
+## Apps and their build commands
+
+One row per application root. A seat `cd`s into the app it touched and runs THAT app's commands — the
+wrong app builds green.
+
+| App | Path | Test | Production build |
+|-----|------|------|------------------|
+<!-- init: scan — angular.json projects, apps/*, packages/* with a build script, web/* and services/* under src/,
+     a *.csproj that is an executable; the test and build commands from each root's own scripts or the
+     solution. fill — one row per app, commands verbatim. absent — "| (none detected) | fill this in: each app
+     root, its test command, its production build command | | |" -->
+
+## The evidence tools
+
+Scripts that make a claim checkable. Each one exists because a green run once meant nothing.
+
+| Script | What it proves | Read with |
+|---|---|---|
+| `verify-staged` (the loop pack's bin) | The staged list matches the list you meant to stage — `git add` drops ignored paths with exit 0 and no output. It validates the list it is GIVEN, never that list's completeness: pair it with `git diff --name-only` and `git ls-files --others --exclude-standard` | [testing](../patterns/testing.md) § The run protocol |
+<!-- init: scan — scripts/ files with a .SYNOPSIS or a header comment that names what they check.
+     fill — one row each. absent — leave the verify-staged row alone. -->
+
+---
+
+> **Other folders:** `research/` = the running tab of ideas (future-state, not built; archived *with* its
+> working docs when shipped). `working/` = in-flight session docs / handoffs (one effort may chain several).
+> `archive/` = completed efforts grouped by topic — research + working docs filed together (frozen history).
+<!-- init: if docs/ held files or folders outside the loop's eight before init ran, list them here in one
+     line each as "repo-owned, outside the loop's shape" so a reader knows they were seen and left alone. -->

package/templates/docs/infrastructure/background-work.md

@@ -0,0 +1,53 @@
+# Background Work
+
+> What runs outside a request in this repository — workers, queues, schedulers — and how long-running,
+> multi-stage work is orchestrated. Last verified {today}.
+<!-- meta: type=infrastructure; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — queue / worker / scheduler libraries (a service bus, RabbitMQ, SQS, BullMQ, Hangfire,
+     Quartz, Celery, sidekiq, a cron), a worker project or folder, the message contracts.
+     fill — two to four sentences: what runs in the background, on what transport, triggered by what.
+     absent — this doc is only drafted when a queue, worker or scheduler is found. -->
+
+## Sync vs async — the decision
+
+| Work | The one way to build it | Notifies the client? |
+|------|-------------------------|----------------------|
+<!-- init: fill — one row per kind of work the repo has (CRUD: sync; ingest/index/fan-out: a command to
+     the queue), with the sentence "there is no runtime flag — the kind of work picks the path" and the
+     rule for reaching for a queue (two or more of: duration, fan-out, burstiness, durability, decoupling).
+     absent — "| (no async kinds detected) | every write is synchronous today | no |" -->
+
+## Workers, queues, schedulers
+
+<!-- init: fill — the worker's entry point, how a handler is registered, the message naming (commands
+     imperative, events past-tense; subject conventions), retries and idempotency, how a worker calls back
+     into the API and with what identity.
+     absent — "No worker detected — fill this in." -->
+
+## Long-running workflows
+
+<!-- init: scan — a saga / orchestration / state-machine base class, a job with stages.
+     fill — the shape (stages, per-item progress, exactly-once stage transitions and what guarantees them,
+     progress reporting to the client), one REAL workflow as the example, then `### Rules`.
+     absent — "No multi-stage workflow detected — fill this in when one appears: how stages chain, how a
+     stage transition happens exactly once, how progress is reported." -->
+
+## Gotchas
+
+<!-- init: scan — comments in the worker/handler code, CONTRIBUTING notes.
+     fill — one `### Gotcha:` per written-down warning, with symptom, cause, remedy, source file.
+     absent — "No background-work gotchas written down yet — fill this in the first time one bites." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+
+## Lineage
+- **Related** — [backend-patterns](../patterns/backend-patterns.md) · [realtime-events](realtime-events.md)

package/templates/docs/infrastructure/realtime-events.md

@@ -0,0 +1,54 @@
+# Realtime Events
+
+> How server-side events reach the client in this repository, and the poke/refetch pattern that keeps
+> the two consistent. Last verified {today}.
+<!-- meta: type=infrastructure; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — the realtime library on each side (signalr, socket.io, ws, sse, pusher, ably, phoenix
+     channels), the hub / channel / gateway classes, the client connection service.
+     fill — two to four sentences: the transport, who connects, what travels (events, not data).
+     absent — this doc is only drafted when a realtime library is found. -->
+
+## The poke/refetch pattern
+
+The server sends a small **poke** (an event naming what changed, and a correlation id when the change
+answers a request); the client **refetches** the affected read through its normal data path. Events carry
+identity, not payload — the read stays the one source of shape, and a missed event costs one refetch,
+never a divergent copy.
+
+<!-- init: scan — an existing event/notification type and its client handler.
+     fill — one REAL event as the example (server emit, client handler), and the correlation-id rule if the
+     repo uses one (a long-running command returns an id; the completion event carries it; the client
+     clears its pending state on match).
+     absent — "No event/handler pair found — fill this in with the first one." -->
+
+## Backend
+
+<!-- init: fill — the hub/channel classes, how a feature emits, the user/connection identity rule (which
+     claim keys a connection — a wrong claim finds no connections silently), the auth on the connection.
+     absent — "No server-side emitter detected — fill this in." -->
+
+## Frontend
+
+<!-- init: fill — the connection service, how a feature registers handlers, the guard every handler
+     carries (skip events for a different entity than the one loaded), reconnect and its catch-up.
+     absent — "No client-side handler registry detected — fill this in." -->
+
+## Gotchas
+
+<!-- init: scan — comments in the hub/handler code, CONTRIBUTING notes.
+     fill — one `### Gotcha:` per written-down warning, with symptom, cause, remedy, source file.
+     absent — "No realtime gotchas written down yet — fill this in the first time one bites." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+
+## Lineage
+- **Related** — [backend-patterns](../patterns/backend-patterns.md) · [frontend-patterns](../patterns/frontend-patterns.md) · [background-work](background-work.md)

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

@@ -0,0 +1,96 @@
+# Backend Patterns
+
+> Rules and conventions for the server side of this repository. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — the server-side project files (*.csproj, *.sln*, go.mod, pyproject.toml, Cargo.toml,
+     a Node service's package.json) and their frameworks.
+     fill — two to four sentences: what the server side is (an API, a worker, a CLI), the framework, and
+     the claim "every server-side feature follows these conventions; read this before writing any
+     server-side code."
+     absent — "No server-side stack detected — fill this in: what runs server-side here, if anything." -->
+
+## Stack
+
+<!-- init: scan — runtime + version, web framework, persistence library, database, messaging, DI,
+     validation, serialization — each from a manifest with its version.
+     fill — one bullet per item: name, version, role.
+     absent — "No server-side dependencies detected — fill this in: the runtime, the framework, the data
+     access library, the database." -->
+
+## Feature folder structure
+
+<!-- init: scan — the folder layout two deep under the server-side root; one existing feature folder.
+     fill — an ASCII tree of ONE real feature as it exists, with a comment per folder saying what goes
+     there, then one sentence on when a feature grows a second sub-folder (a service, a second entity).
+     absent — "No feature layout detected — fill this in: where an endpoint, a model, a query and a
+     service go, as a tree." -->
+
+```
+{root}/
+  {Feature}/
+    ...
+```
+
+## Data layer
+
+<!-- init: scan — the persistence library, an existing entity/model file, a base class or interface
+     every entity shares, the migration or schema tool, one repository/data-access file.
+     fill — the rule for an entity (base class, ids, timestamps, ownership fields), one REAL entity as the
+     example, "the one way to query" (ORM vs raw SQL and when each), then `### Rules` as bold-lead
+     bullets and any `### Gotcha:` the repo has written down (cite the file).
+     absent — "No persistence layer detected — fill this in: how data is modelled, stored and queried." -->
+
+### Rules
+
+<!-- init: fill — bold-lead imperative bullets, each testable, each citing its source when the repo wrote
+     it down (a CONTRIBUTING section, an analyzer rule, a base class docstring).
+     absent — "- No data-layer rules found written down — fill this in: the entity contract, the naming,
+     the one way to query." -->
+
+## API layer
+
+<!-- init: scan — the web framework, one existing endpoint/handler/controller, the routing convention (a
+     global prefix, plural resources), how business logic is shared between transports if there are two.
+     fill — one REAL endpoint as the example, the route convention as a table (pattern, example, resulting
+     URL), then `### Rules`.
+     absent — "No HTTP layer detected — fill this in: how a request enters and what a handler owns." -->
+
+### Rules
+
+<!-- init: absent — "- No API-layer rules found written down — fill this in: request/response shape,
+     where validation lives, what a handler may and may not do." -->
+
+## Write paths — sync, or long-running
+
+<!-- init: scan — a queue, a worker, a job runner, a saga/orchestration in the dependencies or folders.
+     fill — the decision table `Work | The one way to build it | Pokes the client?` with the sentence
+     "there is no runtime flag — the kind of work picks the path", and the rule for when a command/queue
+     is warranted (duration, fan-out, burstiness, durability, decoupling — two or more).
+     absent — "No asynchronous write path detected — every write is a synchronous request/response;
+     fill this in when a queue or worker appears." -->
+
+## Registration & DI
+
+<!-- init: scan — the composition root (Program.cs, main.go, app.py, index.ts), how features register
+     themselves, the DI conventions in use.
+     fill — where a new feature registers what, as a short table (Class type | How it is registered),
+     and the one rule that bites (an unregistered X silently does not exist).
+     absent — "No composition root detected — fill this in: where a new feature registers itself." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+<!-- init: scan — every file the sections above named: the base entity, the db context, the composition
+     root, the example feature's files.
+     fill — one row per file, verbatim path.
+     absent — "| (none detected) | fill this in: the base entity, the data context, the composition root |" -->
+
+## Lineage
+- **Related** — [vertical-slice-anatomy](vertical-slice-anatomy.md) · [testing](testing.md) · [codegen](codegen.md)

package/templates/docs/patterns/codegen.md

@@ -0,0 +1,69 @@
+# Code Generation
+
+> What is generated in this repository, from what, by which command — and the one rule: never hand-write
+> a generated file. Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — generated/ folders, codegen configs (codegen.ts / codegen.yml, openapi*, *.proto,
+     tgconfig.json, prisma/, graphql-codegen, source generators in *.csproj), package.json scripts named
+     gen / codegen / generate, a scripts/ file that orchestrates them.
+     fill — an ASCII diagram of each pipeline (source, tool, output) and a table
+     `Pipeline | Tool | Input | Output | Purpose`, one row per pipeline found.
+     absent — "No code generation detected — fill this in when a pipeline appears (an OpenAPI client, a
+     GraphQL client, a protobuf, an ORM client). Until then there is no generated folder to protect." -->
+
+## Running codegen
+
+<!-- init: scan — the orchestrating script or the per-pipeline commands, and their preconditions (a
+     built binary, a running server).
+     fill — ONE fenced block: the exact command(s) from the repo root, with a comment per line naming its
+     precondition. This is the command every seat runs; the skills point here.
+     absent — "No codegen command detected — fill this in: the exact invocation from the repo root." -->
+
+```
+{the exact command}          # precondition: {what must be built or running}
+```
+
+## What is generated — never hand-written
+
+<!-- init: fill — the list of generated folders/files, verbatim paths, each with the tool that owns it and
+     the header it carries ("AUTO-GENERATED — DO NOT EDIT"). Then the rule:
+     "**Never hand-write or manually edit files under these paths.** Run the command above; a hand-written
+     'generated' file is overwritten on the next run and drifts silently until then."
+     absent — "No generated folders detected — fill this in when one appears." -->
+
+## Adding a generated type — checklist
+
+<!-- init: scan — how a source type opts into generation (an attribute, an export, a schema entry).
+     fill — a checklist: mark the source (the attribute/export), run the command, verify the output file
+     exists and compiles, commit source and output together.
+     absent — "- No opt-in mechanism detected — fill this in: how a type enters the pipeline." -->
+
+## Removing a generated type — checklist
+
+<!-- init: fill — the mirror checklist: remove the source mark, run the command, delete the orphaned
+     output, grep consumers.
+     absent — "- No pipeline detected — fill this in when one appears." -->
+
+## Gotchas
+
+<!-- init: scan — comments in the codegen config or script that warn about something; CONTRIBUTING notes.
+     fill — one `### Gotcha:` per warning found, each with symptom, cause, remedy, and the file it came
+     from.
+     absent — "No codegen gotchas written down yet — fill this in the first time one bites." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+<!-- init: scan — every config, script and generated folder named above.
+     fill — one row per file, verbatim path.
+     absent — "| (none detected) | fill this in: the configs, the script, the output folders |" -->
+
+## Lineage
+- **Related** — [backend-patterns](backend-patterns.md) · [frontend-patterns](frontend-patterns.md) · [testing](testing.md)