@rashidee/co2 1.2.5

package/plugin/skills/specgen-node-cli-web/references/server-patterns.md

@@ -0,0 +1,247 @@
+# Server Patterns — specgen-node-cli-web
+
+Canonical patterns for the data directory (root spec Section 5), database layer
+(Section 6), and Hono server composition (Section 7).
+
+## 1. Data directory resolution
+
+Per-platform, XDG-compliant, keyed by the package name. Resolve manually (shown below) or
+via `env-paths` — no heavier dependency:
+
+```ts
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync } from 'node:fs'
+
+export function resolveDataDir(override?: string): string {
+  const dir = override ?? defaultDataDir()
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+function defaultDataDir(): string {
+  const app = '{{PACKAGE_NAME}}'
+  switch (process.platform) {
+    case 'darwin':
+      return join(homedir(), 'Library', 'Application Support', app)
+    case 'win32':
+      return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), app)
+    default:
+      return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), app)
+  }
+}
+```
+
+Contents: `app.db` (+ WAL/SHM files), `config.json`, `logs/` (optional),
+[If FileStorage] `files/`. Rules:
+
+- Created on first run with `0700` permissions.
+- The package installation directory is read-only at runtime (global npm installs may not
+  be writable) — NEVER write anything next to the installed code.
+
+## 2. config.json
+
+Zod-validated on load; unknown keys rejected (`.strict()`). Absent file = all defaults.
+
+```ts
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { z } from 'zod'
+
+export const configSchema = z
+  .object({
+    port: z.number().int().min(1).max(65535).optional(),
+    host: z.string().optional(),
+    // [If HttpIntegration] apiBaseUrl: z.string().url().optional(),
+    // ...one key per config-driven setting discovered in the PRD
+  })
+  .strict()
+
+export type AppConfig = z.infer<typeof configSchema>
+
+export function loadConfig(dataDir: string): AppConfig {
+  const file = join(dataDir, 'config.json')
+  if (!existsSync(file)) return {}
+  return configSchema.parse(JSON.parse(readFileSync(file, 'utf8')))
+}
+```
+
+## 3. Database connection factory
+
+No module-level singletons bound to `process.env` — the factory takes the resolved
+data-dir path (or `:memory:`) so tests can inject in-memory databases. The three pragmas
+are mandatory:
+
+```ts
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import * as schema from './schema.js'
+
+export type Db = ReturnType<typeof openDatabase>
+
+export function openDatabase(dataDirOrMemory: string) {
+  const path =
+    dataDirOrMemory === ':memory:' ? ':memory:' : join(dataDirOrMemory, 'app.db')
+  const sqlite = new Database(path)
+  sqlite.pragma('journal_mode = WAL')
+  sqlite.pragma('foreign_keys = ON')
+  sqlite.pragma('busy_timeout = 5000')
+  return drizzle(sqlite, { schema })
+}
+
+export function runMigrations(db: Db): void {
+  // In the published package, drizzle/ sits next to dist/ — resolve relative to the
+  // bundle, never relative to process.cwd().
+  const migrationsFolder = join(dirname(fileURLToPath(import.meta.url)), '..', 'drizzle')
+  migrate(db, { migrationsFolder })
+}
+```
+
+Migrations run automatically on every `start` before the server binds. Idempotent; no
+separate migrate command for end users. Migration SQL files are generated by
+`drizzle-kit generate`, committed in `server/drizzle/`, and shipped in the package —
+never hand-edited after commit.
+
+## 4. Hono app factory
+
+One Hono app serves everything. Middleware order is fixed:
+**request-id → logger → session resolution → route guards → routes.**
+
+```ts
+import { Hono } from 'hono'
+import { requestId } from 'hono/request-id'
+import { secureHeaders } from 'hono/secure-headers'
+import { serveStatic } from '@hono/node-server/serve-static'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Db } from './db/index.js'
+import { requestLogger } from './lib/logger.js'
+import { sessionMiddleware, forcedChangeGuard } from './auth/middleware.js'
+import { authRoutes } from './features/auth/routes.js'
+import { userRoutes } from './features/users/routes.js'
+// ...one import per module feature
+
+export interface AppDeps {
+  db: Db
+  dataDir: string
+}
+
+export function createApp({ db, dataDir }: AppDeps) {
+  const app = new Hono<{ Variables: { db: Db; user: SessionUser | null } }>()
+    .use('*', requestId())
+    .use('*', requestLogger())
+    .use('*', secureHeaders())
+    .use('*', async (c, next) => {
+      c.set('db', db)
+      await next()
+    })
+    .use('/api/*', sessionMiddleware())
+    .use('/api/*', forcedChangeGuard())
+
+  const api = app
+    .route('/api/auth', authRoutes)
+    .route('/api/users', userRoutes)
+    // .route('/api/{{module}}', {{module}}Routes)
+    .get('/api/health', (c) =>
+      c.json({ status: 'ok', version: APP_VERSION, uptimeSeconds: process.uptime() }),
+    )
+
+  const staticRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'static')
+  app.use('*', serveStatic({ root: staticRoot }))
+  app.get('*', serveStatic({ root: staticRoot, rewriteRequestPath: () => '/index.html' }))
+
+  return api
+}
+
+export type AppType = ReturnType<typeof createApp>
+```
+
+Rules:
+- `/api/*` routes are mounted before `serveStatic`; the SPA fallback rewrites unknown
+  non-API GETs to `index.html` for client-side routing.
+- Security headers on ALL responses via `hono/secure-headers`.
+- **CORS is NOT enabled** — the UI is same-origin by construction. Never add permissive
+  CORS.
+
+## 5. Typed API contract (hono/client RPC)
+
+Routes are defined with `@hono/zod-validator`; the route tree's type (`AppType`) is
+exported so `web/` consumes a fully typed client. The API contract is compiler-enforced
+end to end — no OpenAPI codegen step.
+
+```ts
+// packages/web/src/lib/api.ts
+import { hc } from 'hono/client'
+import type { AppType } from '@{{PACKAGE_NAME}}/server/app'
+
+export const api = hc<AppType>('/', {
+  fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
+    const res = await fetch(input, { ...init, credentials: 'same-origin' })
+    if (res.status === 403) {
+      const body = await res.clone().json().catch(() => null)
+      if (body?.code === 'PASSWORD_CHANGE_REQUIRED') {
+        window.location.assign('/force-change-password')
+      }
+    }
+    return res
+  },
+})
+```
+
+Route definition pattern (per feature):
+
+```ts
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { createItemSchema, listQuerySchema } from '@{{PACKAGE_NAME}}/core/schemas/{{domain}}'
+import { requireRole } from '../../auth/middleware.js'
+import * as service from './service.js'
+
+export const {{module}}Routes = new Hono<AppEnv>()
+  .get('/', zValidator('query', listQuerySchema), (c) =>
+    c.json(service.list(c.var.db, c.req.valid('query'))),
+  )
+  .post('/', requireRole('admin'), zValidator('json', createItemSchema), (c) =>
+    c.json(service.create(c.var.db, c.req.valid('json')), 201),
+  )
+```
+
+## 6. Structured logger
+
+No logging framework — a small JSON-lines logger in `server/src/lib/logger.ts`,
+picocolors-highlighted only when stdout is a TTY. The one-time start status block is the
+sole non-structured output; everything after it goes through the logger.
+
+```ts
+import pc from 'picocolors'
+
+type Level = 'info' | 'warn' | 'error'
+
+export function log(level: Level, message: string, fields: Record<string, unknown> = {}): void {
+  const entry = { time: new Date().toISOString(), level, message, ...fields }
+  const line = JSON.stringify(entry)
+  if (!process.stdout.isTTY) {
+    process.stdout.write(`${line}\n`)
+    return
+  }
+  const color = level === 'error' ? pc.red : level === 'warn' ? pc.yellow : pc.dim
+  process.stdout.write(`${color(line)}\n`)
+}
+
+export function requestLogger() {
+  return async (c: HonoContext, next: () => Promise<void>) => {
+    const started = performance.now()
+    await next()
+    log('info', 'request', {
+      requestId: c.var.requestId,
+      method: c.req.method,
+      path: c.req.path,
+      status: c.res.status,
+      durationMs: Math.round(performance.now() - started),
+    })
+  }
+}
+```

package/plugin/skills/specgen-node-cli-web/references/spec-template.md

@@ -0,0 +1,401 @@
+# Specification Template — Self-Hosted Node.js CLI Web Application
+
+This is the authoritative template for the generated specification. The specification is
+split into **two types of files**:
+
+1. **`SPECIFICATION.md`** (root) — Table of Contents, monorepo + shared infrastructure,
+   CLI contract, data directory, database, server composition, bootstrap, auth baseline,
+   SPA shell, testing, packaging. Generated once per application.
+2. **`<module-name>/SPEC.md`** (per-module) — Self-contained module blueprint spanning
+   the server feature and the SPA feature. Generated once per business module from
+   PRD.md, PLUS the mandatory `user-management/SPEC.md`.
+
+```
+specification/
+├── SPECIFICATION.md
+├── user-management/
+│   └── SPEC.md
+├── inventory/
+│   └── SPEC.md
+└── ...
+```
+
+Placeholders use `{{VARIABLE}}` syntax and must be replaced with actual values.
+
+---
+
+# Part A: Root SPECIFICATION.md
+
+---
+
+## Table of Contents
+
+Generate a TOC with anchor links. Include a **Modules** section linking to each module's
+`SPEC.md` (user-management first):
+
+```markdown
+## Table of Contents
+
+### Shared Infrastructure
+- [1. Project Overview](#1-project-overview)
+- [2. Monorepo & Workspace Configuration](#2-monorepo--workspace-configuration)
+- ...
+
+### Modules
+- [User Management (mandatory)](user-management/SPEC.md)
+- [Inventory](inventory/SPEC.md)
+- ...
+```
+
+---
+
+## Section 1: Project Overview
+
+```
+# {{APPLICATION_NAME}} — Technical Specification
+
+## 1. Project Overview
+
+**Application Name**:  {{APPLICATION_NAME}}
+**Package / Binary**:  {{PACKAGE_NAME}}          (npm package name AND executable command)
+**Install**:           npm install -g {{PACKAGE_NAME}}
+**Start**:             {{PACKAGE_NAME}} start    → http://<LAN-IP>:3000
+**Node.js Version**:   22 LTS (engines.node ">=22")
+**Description**:       {{APP_DESCRIPTION}}
+**Versions Covered**:  v1.0.0 — v{{LATEST_VERSION}}
+
+### Architecture Model
+Single-process, local-first. One Node process serves the REST API (Hono) and the
+embedded pre-built React SPA. All state lives in the per-user data directory. There is
+no hosted backend, no database server, no Docker.
+
+### Optional Components (Auto-Determined)
+**DataGrid**:         {{yes|no}}
+**Charts**:           {{yes|no}}
+**DatePickers**:      {{yes|no}}
+**RichText**:         {{yes|no}}
+**FileStorage**:      {{yes|no}}
+**InProcessJobs**:    {{yes|no}}
+**HttpIntegration**:  {{yes|no}}
+**ExtraCommands**:    {{list or none}}
+
+### Technology Stack
+(Render the core stack table from SKILL.md, plus selected optional versions)
+
+### CLI Commands
+| Command       | Description                                    | Version |
+|---------------|------------------------------------------------|---------|
+| start         | Start the web application (foreground)         | v1.0.0  |
+| status        | Show whether an instance is reachable          | v1.0.0  |
+| reset-admin   | Regenerate the admin password offline          | v1.0.0  |
+| {{extra}}     | {{description}}                                | {{ver}} |
+
+### User Roles
+| Role  | Source (mockup folder) | Capabilities summary |
+|-------|------------------------|----------------------|
+| admin | mockup/admin/          | Full access + user management |
+| user  | mockup/user/           | {{...}} |
+
+### Module Index
+| Module | Spec File | Tables | SPA Routes |
+|--------|-----------|--------|------------|
+| User Management (mandatory) | [user-management/SPEC.md](user-management/SPEC.md) | users, sessions | /login, /force-change-password, /users, /settings |
+| {{Module}} | [{{module}}/SPEC.md]({{module}}/SPEC.md) | {{tables}} | {{routes}} |
+```
+
+---
+
+## Section 2: Monorepo & Workspace Configuration
+
+Render the full monorepo tree (from SKILL.md, with actual feature/module names
+substituted), then complete copy-pasteable config files:
+
+- `pnpm-workspace.yaml` (`packages: ["packages/*"]`)
+- Root `package.json` with the workspace scripts — exactly these:
+
+```json
+{
+  "name": "{{PACKAGE_NAME}}-workspace",
+  "private": true,
+  "version": "{{VERSION}}",
+  "engines": { "node": ">=22" },
+  "packageManager": "pnpm@9.15.0",
+  "scripts": {
+    "dev": "pnpm --parallel --filter server --filter web dev",
+    "build": "pnpm --filter core --filter server --filter web --filter cli build",
+    "check": "tsc -b && biome check .",
+    "fix": "biome check --write .",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "smoke": "node packages/cli/dist/index.js --version && node scripts/smoke-start.mjs",
+    "verify": "pnpm check && pnpm test && pnpm build && pnpm smoke"
+  }
+}
+```
+
+- `biome.json` (formatter + linter, recommended rules, 100-char line width)
+- Root `tsconfig.json` (composite project references: core → server → web → cli) and each
+  package's `tsconfig.json` with `"strict": true`
+- `packages/core/package.json`, `packages/server/package.json`,
+  `packages/web/package.json` (all `"private": true`)
+
+State the structural rules: feature-folder colocation, no barrel files, <300 lines/file,
+Zod at every boundary, `any` forbidden, types via `z.infer<>`.
+
+---
+
+## Section 3: Published CLI Package & Build Pipeline
+
+Read `references/cli-packaging-patterns.md`. Must include, copy-pasteable:
+
+- `packages/cli/package.json` — `name: {{PACKAGE_NAME}}`, `bin`, `files: ["dist",
+  "static", "drizzle"]`, `engines`, `better-sqlite3` as the ONLY runtime dependency,
+  `prepublishOnly: "pnpm -w verify"`
+- `packages/cli/tsup.config.ts` — entry `src/index.ts`, `format: ["esm"]`, shebang
+  preserved, `external: ["better-sqlite3"]`
+- The three-step publish pipeline (bundle → vite build + copy to `static/` → copy
+  `drizzle/`) as npm scripts
+- Install-weight budget note: tarball SHOULD stay under 5 MB excluding better-sqlite3;
+  new runtime dependencies require explicit human approval
+- Local install check: `npm pack` → `npm i -g ./<tarball>` → smoke sequence
+
+### Section 3a: Application Version Configuration
+
+The `packages/cli/package.json` `version` field MUST be set to the version value derived
+from the version argument provided during skill invocation (e.g., `1.0.3`). If multiple
+versions were provided, use the highest one.
+
+- `{{PACKAGE_NAME}} --version` prints it (commander `.version()` fed from the bundled
+  package.json)
+- The `start` status block prints it
+- The SPA footer renders `v{{VERSION}}` (served from a `/api/system/info` route — the SPA
+  must not hardcode it)
+
+---
+
+## Section 4: CLI Contract
+
+Read `references/cli-packaging-patterns.md`. Must include:
+
+- The full command surface with flags:
+  ```
+  {{PACKAGE_NAME}} start [--port <n>] [--host <addr>] [--data-dir <path>]
+  {{PACKAGE_NAME}} status
+  {{PACKAGE_NAME}} reset-admin
+  {{PACKAGE_NAME}} --version | --help
+  ```
+- `src/index.ts` (shebang + commander program) — complete sample
+- `commands/start.ts` — option resolution order (flag → `APP_PORT`/`APP_HOST`/
+  `APP_DATA_DIR` env → config.json → default 3000 / 0.0.0.0), port-in-use failure message
+  naming `--port`, LAN IP detection, the single status block, graceful shutdown closing
+  the SQLite handle — complete sample
+- `commands/status.ts` and `commands/reset-admin.ts` — complete samples
+- Explicit statements: foreground only, NO daemon/forking logic; handlers are thin
+  (parse → Zod → delegate to server/core)
+- [If ExtraCommands] one subsection per extra command with traceability IDs
+
+---
+
+## Section 5: Data Directory & Configuration
+
+Read `references/server-patterns.md`. Must include:
+
+- Per-platform resolution table (Linux `~/.local/share/{{PACKAGE_NAME}}/`, macOS
+  `~/Library/Application Support/{{PACKAGE_NAME}}/`, Windows
+  `%LOCALAPPDATA%/{{PACKAGE_NAME}}/`) and the resolver sample (manual or `env-paths`)
+- Contents: `app.db` (+ WAL/SHM), `config.json`, `logs/` (optional),
+  [If FileStorage] `files/`
+- Creation on first run with `0700` permissions; install dir treated read-only
+- `config.json` Zod schema (unknown keys rejected) with every key, type, and default —
+  complete sample
+- Auto-migration on every start before the server binds, against the shipped `drizzle/`
+  folder
+
+---
+
+## Section 6: Database Layer
+
+Must include, with complete samples:
+
+- `server/src/db/schema.ts` — Drizzle definitions for `users` + `sessions` (from
+  `references/auth-patterns.md`) PLUS every module table from the model files,
+  field-for-field
+- `server/src/db/index.ts` — connection factory taking the data-dir path (or `:memory:`),
+  mandatory pragmas: WAL, `foreign_keys = ON`, `busy_timeout = 5000`; no module-level
+  singletons
+- `drizzle.config.ts` and the `db:generate` workflow; migrations committed in
+  `server/drizzle/` and shipped in the published package
+
+---
+
+## Section 7: Server Composition
+
+Read `references/server-patterns.md`. Must include:
+
+- `server/src/app.ts` app factory — complete sample showing middleware order
+  (request-id → logger → session resolution → route guards → routes), `/api/*` route
+  mounting, `secure-headers`, `serveStatic` + SPA fallback
+- The exported `AppType` and the `hono/client` consumption pattern
+- Health endpoint (`GET /api/health`) used by `status` and the smoke test
+- Statement: CORS is NOT enabled; never add it
+- `server/src/lib/logger.ts` — structured JSON-line logger, picocolors-highlighted when
+  TTY — complete sample
+
+---
+
+## Section 8: First-Run Bootstrap
+
+Read `references/auth-patterns.md`. Must include `server/src/db/bootstrap.ts` complete
+sample: users-table-empty check → create `admin` (role `admin`,
+`must_change_password = true`) with a cryptographically random 16-character password
+(base58/alphanumeric, no ambiguous characters) → return credentials for one-time printing
+inside the start status block. Plaintext never written to file or log; no-op once any
+user exists (verified by test).
+
+---
+
+## Section 9: Authentication & User Lifecycle
+
+Read `references/auth-patterns.md`. Must include, with complete samples:
+
+- scrypt hash/verify (`node:crypto`, N=2^15, r=8, p=1, `salt:hash`, `timingSafeEqual`)
+- Password policy Zod schema in `core/` (min 10 chars, reject username-as-password, no
+  composition rules) shared by UI and API
+- Session issue/resolve/revoke: 32-byte random token, SHA-256 hash stored, sliding
+  expiry, 30-day absolute cap; cookie `httpOnly` `SameSite=Lax` `Path=/`, `Secure` only
+  over HTTPS
+- In-memory login rate limiter (fixed window, 10 / 15 min per username+IP)
+- Forced-change middleware returning `403 PASSWORD_CHANGE_REQUIRED` on every route except
+  login / change-password / logout
+- The user management flow table (create / forced change / change / admin reset /
+  delete with last-admin invariant) and the MUST-NOT list (no email, registration,
+  OAuth, JWT)
+
+---
+
+## Section 10: Web SPA Shell
+
+Must include:
+
+- `packages/web/vite.config.ts` (dev proxy to the server port; build output consumed by
+  the publish pipeline), Tailwind v4 CSS-first setup (`@import "tailwindcss"` + `@theme`
+  tokens extracted from the mockups/design system), vendored shadcn/ui conventions
+- `web/src/lib/api.ts` — typed `hono/client` RPC client with the 403
+  `PASSWORD_CHANGE_REQUIRED` interceptor hard-redirecting to `/force-change-password` —
+  complete sample
+- Router setup with the mandatory routes (`/login`, `/force-change-password`, `/users`,
+  `/settings`) plus per-module routes; role-guarded navigation derived from mockups
+- Shared layout (sidebar + topbar + footer rendering `v{{VERSION}}` from
+  `/api/system/info`)
+
+---
+
+## Section 11: Testing Strategy
+
+Read `references/testing-patterns.md`. Must include the Vitest setup (`:memory:` SQLite
+via the connection factory with real migrations — never mock the DB), the mandatory
+coverage list (forced-change gating on every guarded route, last-admin invariant, session
+revocation on password change, rate limiting, bootstrap no-op on second start), the
+`scripts/smoke-start.mjs` complete sample, and the Playwright E2E scenario (first-run
+login with printed credentials → forced change → create second user → second user's
+forced change → password change from settings).
+
+---
+
+## Section 12: Packaging & Distribution
+
+npm-only distribution: `files` whitelist, `engines`, `bin`, `prepublishOnly` runs
+`pnpm verify`, semantic versioning guidance, the `npm pack` → global-install →
+smoke-sequence pre-publish check, and the note that daemonization/TLS are the operator's
+concern (systemd/pm2/reverse proxy examples in prose, never in code).
+
+---
+
+# Part B: Per-Module `<module-name>/SPEC.md`
+
+Every module file is **self-contained** — a coding agent implements it independently
+after the shared infrastructure exists. `user-management/SPEC.md` is always generated
+and follows this same template with the auth blueprint as its content.
+
+## Template
+
+```
+# {{MODULE_NAME}} — Module Specification
+
+> Part of [{{APPLICATION_NAME}} Technical Specification](../SPECIFICATION.md).
+> Implement after the shared infrastructure (root spec sections 2–10) is in place.
+
+## 1. Traceability
+
+### User Stories
+| ID | Version | Summary | Implemented By |
+|----|---------|---------|----------------|
+| {{USXX00001}} | [v1.0.0] | {{summary}} | {{routes.ts handler / page component}} |
+
+### Non-Functional Requirements
+| ID | Version | Requirement | Technical Decision |
+|----|---------|-------------|--------------------|
+
+### Constraints
+| ID | Version | Constraint | Enforcement Point |
+|----|---------|------------|-------------------|
+
+### Mockup Screens
+| Screen | Role | SPA Route | Page Component |
+|--------|------|-----------|----------------|
+
+### Removed / Replaced
+| Removed ID | Removed In | Replaced By | Reason |
+|-----------|------------|-------------|--------|
+
+## 2. Data Model (Drizzle)
+The module's tables in server/src/db/schema.ts — field-for-field from the model files,
+with relations and the generated migration filename.
+
+## 3. Shared Schemas (packages/core)
+core/src/schemas/{{domain}}.ts — Zod schemas for entities, create/update inputs, and
+query params; exported types via z.infer<>. Complete sample.
+
+## 4. Service (packages/server)
+features/{{module}}/service.ts — pure functions taking the db handle; business rules
+from constraints as explicit invariants. No HTTP concerns, no terminal I/O.
+Complete sample.
+
+## 5. Routes (packages/server)
+features/{{module}}/routes.ts — Hono sub-app with @hono/zod-validator on every body/
+query/param, role guards, and typed responses; mounted in app.ts under /api/{{module}}.
+Complete sample. Route table: method, path, guard, request schema, response type,
+story IDs.
+
+## 6. SPA Feature (packages/web)
+- Page components under web/src/routes/ — one per mockup screen, shadcn/ui components
+  matching the mockup layout ([If DataGrid] shadcn Data Table / TanStack Table;
+  [If DatePickers] react-day-picker; [If RichText] Tiptap)
+- Forms with the shared core/ Zod schemas
+- Typed data access via the hono/client RPC client (no hand-written fetch paths)
+- Route definitions + role-guarded navigation entries
+Complete samples for every component.
+
+## 7. Tests
+- Vitest: service tests + route tests over :memory: with real migrations; every
+  constraint invariant has a test
+- Playwright: the module's user-visible flows appended to the E2E suite
+```
+
+## Special case: `user-management/SPEC.md`
+
+Same template; its content comes from `references/auth-patterns.md`:
+
+- Tables: `users`, `sessions` (Section 2)
+- Schemas: password policy, login input, user create/update (Section 3)
+- Service: bootstrap, hashing, session lifecycle, user CRUD with last-admin invariant
+  (Section 4)
+- Routes: `POST /api/auth/login`, `POST /api/auth/logout`,
+  `POST /api/auth/change-password`, `GET /api/auth/me`, `GET/POST/PATCH/DELETE
+  /api/users...` with admin guards (Section 5)
+- SPA: `/login`, `/force-change-password`, `/users`, `/settings` pages (Section 6)
+- Tests: the mandatory security coverage list (Section 7)
+
+When PRD.md defines its own auth/user stories, merge their IDs into this file's
+traceability tables. PRD phrasing never weakens the security invariants — flag conflicts
+to the user instead.