From 7baf2dd08c4f54d1f8cb0ace387f0fcfa11cb338 Mon Sep 17 00:00:00 2001
From: Mao Nakamoto <41178744+maonakamoto@users.noreply.github.com>
Date: Wed, 22 Jul 2026 19:47:34 +0200
Subject: [PATCH] chore(ci): add single verify script as SSOT for pre-build
 checks

Bundle the pre-build check chain (lint -> typecheck -> unit tests with
coverage) into one `npm run verify` script so local and CI run the exact
same gate and cannot drift. Add a `typecheck` script (tsc --noEmit) so the
chain uses named scripts throughout.

CI now calls `npm run verify` verbatim instead of re-listing lint, tsc and
jest inline. The two former check jobs (lint-and-typecheck + unit-tests)
are consolidated into one `verify` job; the coverage artifact upload is
preserved (jest --coverage still enforces coverageThreshold, and jest
auto-enables CI mode via CI=true, so the old `--ci` flag is redundant).
Gate, test set, migrations and deploy are unchanged.

Add AGENTS.md documenting stack, dev/verify commands, Prisma migration
location, and the Vercel deploy path (migrate-on-deploy).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 35 +++++-------------------
 AGENTS.md                | 58 ++++++++++++++++++++++++++++++++++++++++
 package.json             |  2 ++
 3 files changed, 67 insertions(+), 28 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 96b5620a..102b0890 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,8 +7,8 @@ on:
     branches: [master]
 
 jobs:
-  lint-and-typecheck:
-    name: Lint & Type Check
+  verify:
+    name: Verify (lint, typecheck, unit)
     runs-on: ubuntu-latest
 
     steps:
@@ -24,31 +24,10 @@ jobs:
       - name: Generate Prisma client
         run: npx prisma generate
 
-      - name: Lint
-        run: npm run lint
-
-      - name: Type check
-        run: npx tsc --noEmit
-
-  unit-tests:
-    name: Unit Tests
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-
-      - run: npm ci
-
-      - name: Generate Prisma client
-        run: npx prisma generate
-
-      - name: Run unit tests
-        run: npm test -- --ci --coverage
+      # SSOT: identical to `npm run verify` run locally (lint + typecheck +
+      # unit tests with coverage). Jest auto-enables CI mode via CI=true.
+      - name: Verify
+        run: npm run verify
 
       - name: Upload coverage
         if: always()
@@ -61,7 +40,7 @@ jobs:
   build:
     name: Build
     runs-on: ubuntu-latest
-    needs: [lint-and-typecheck, unit-tests]
+    needs: [verify]
 
     steps:
       - uses: actions/checkout@v4
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..f2920c8b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,58 @@
+# AGENTS.md — aoz-housing
+
+Compatibility-based housing placement for AOZ (reduce roommate conflicts, improve
+refugee wellbeing). Serves a vulnerable population — see `CLAUDE.md` for the full
+mission, ethical boundaries (never track medical/immigration/religion), and the
+design-system + Swiss-German UI rules. This file is the quick operational map.
+
+## Stack
+
+Next.js 14 (App Router) · TypeScript (strict) · PostgreSQL + Prisma · Zod (SSOT
+for types) · Tailwind v3 · Jest + Playwright. Deployed on Vercel.
+
+## Everyday commands
+
+```bash
+npm run dev       # Next.js dev server (default :3000)
+npm run verify    # SSOT gate: lint + typecheck + unit tests (with coverage)
+npm run build     # prisma generate && next build
+npm test          # Jest unit tests only
+npm run test:e2e  # Playwright E2E (needs a running Postgres)
+```
+
+## verify — the single source of truth for checks
+
+`npm run verify` runs the exact pre-build check chain: `next lint` →
+`tsc --noEmit` → `jest --coverage` (Jest enforces `coverageThreshold` from
+`jest.config.ts`). CI (`.github/workflows/ci.yml`) calls `npm run verify`
+verbatim, so a green local `verify` means a green CI check stage. Run it before
+committing. Never re-list these checks inline — change them here (`package.json`)
+only.
+
+CI stages: **verify** → **build** → **e2e** (Playwright against a real Postgres
+service container). `build` and `e2e` are gated on `verify` passing.
+
+## Prisma / database
+
+- Schema (SSOT): `prisma/schema.prisma`. Migrations: `prisma/migrations/`.
+- Dev schema change: edit schema → `npx prisma migrate dev --name <change>` →
+  `npm run prisma:generate` → restart dev server.
+- Production migrations run automatically at deploy (see below); never edit an
+  already-applied migration — always add a new one.
+- Seed admin: `npx ts-node --compiler-options '{"module":"CommonJS"}' prisma/seed-admin.ts`
+  (default login code `AOZ-ADMIN1`).
+
+## Deploy path
+
+Vercel. `vercel.json` sets `buildCommand: "npm run prisma:migrate && npm run build"`,
+so `prisma migrate deploy` applies pending migrations against the production DB on
+every deploy. A daily cron hits `/api/cron/notifications` (08:00). Push to
+`master` triggers the deploy; watch it to `Ready` before calling a change shipped.
+
+## Guardrails
+
+- Config is SSOT: factors in `src/lib/config/`, German UI labels in
+  `src/lib/constants/labels/`, design tokens in `src/app/globals.css`. Adding a
+  factor should touch ≤2 files (config + schema).
+- Swiss German everywhere in UI: always umlauts (ä/ö/ü), `ss` never `ß`.
+- Mobile-first; touch targets ≥44px. Full detail in `CLAUDE.md`.
diff --git a/package.json b/package.json
index aa71a449..ae1cbdd7 100644
--- a/package.json
+++ b/package.json
@@ -8,8 +8,10 @@
     "build": "prisma generate && next build",
     "start": "next start",
     "lint": "next lint",
+    "typecheck": "tsc --noEmit",
     "test": "jest",
     "test:e2e": "playwright test",
+    "verify": "npm run lint && npm run typecheck && npm test -- --coverage",
     "prisma:generate": "prisma generate",
     "prisma:migrate": "prisma migrate deploy",
     "prisma:migrate:dev": "prisma migrate dev",