From 55232ba633e5d464954ba9c3d437e8e3f0c42a89 Mon Sep 17 00:00:00 2001
From: Mao Nakamoto <41178744+maonakamoto@users.noreply.github.com>
Date: Wed, 22 Jul 2026 19:53:55 +0200
Subject: [PATCH] ci: add verify SSOT script and make gate strict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a single "verify" npm script (format:check + lint + test + build) as the
one definition of "green", and wire CI to call it verbatim.

Replace the CI gate's `npm run <script> --if-present` calls (which silently
pass if a script is renamed or removed — a false green) with the strict
`npm run verify`, so a missing/renamed gate script fails loudly.

Add AGENTS.md documenting stack, dev commands, verify, manual Supabase
migrations, and the Vercel deploy path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/deploy.yml | 19 +++++------
 AGENTS.md                    | 64 ++++++++++++++++++++++++++++++++++++
 package.json                 |  1 +
 3 files changed, 73 insertions(+), 11 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 21a7ffe9..8937179b 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -20,20 +20,17 @@ jobs:
           node-version: '22'
           cache: 'npm'
 
-      - name: Install dependencies and build
-        run: npm run build:ci
+      - name: Install dependencies
+        run: npm ci
+
+      # Single SSOT gate: format:check + lint + test + build.
+      # Runs verbatim what developers run locally via `npm run verify`.
+      # No --if-present: a missing/renamed gate script fails loudly.
+      - name: Verify (format + lint + test + build)
+        run: npm run verify
         env:
           NEXT_PUBLIC_DEPLOY_TIME: ${{ github.event.head_commit.timestamp }}
 
-      - name: Run format check
-        run: npm run format:check --if-present
-
-      - name: Run linting
-        run: npm run lint --if-present
-
-      - name: Run tests
-        run: npm run test --if-present
-
       - name: Install Vercel CLI
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: npm install -g vercel@latest
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..b67f1a71
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# AGENTS.md — Botsmann
+
+Operating guide for automated agents and new contributors. Mirrors key facts from
+`.claude/CLAUDE.md`. Keep this file in sync when the stack or workflow changes.
+
+## Stack
+
+| Layer      | Technology                     |
+| ---------- | ------------------------------ |
+| Framework  | Next.js 14 (App Router)        |
+| Language   | TypeScript (strict)            |
+| Styling    | Tailwind CSS                   |
+| Database   | Supabase (Postgres)            |
+| Testing    | Jest (unit) + Playwright (e2e) |
+| Deployment | Vercel                         |
+
+## Everyday commands
+
+```bash
+npm install        # install deps
+npm run dev        # local dev server, port 3000
+npm run build      # production build (also type-checks)
+npm run test       # Jest unit tests
+npm run test:e2e   # Playwright end-to-end tests
+```
+
+## verify — the single gate (SSOT)
+
+```bash
+npm run verify     # format:check → lint → test → build
+```
+
+`verify` is the one definition of "green". CI runs it verbatim (see
+`.github/workflows/deploy.yml`), so a local green `verify` means a green CI.
+Run it before declaring any change done. The gate uses explicit script names
+(no `--if-present`): a missing or renamed gate script fails loudly instead of
+silently passing.
+
+## Supabase migrations — MANUAL
+
+Migrations live in `supabase/migrations/` (`NNN_description.sql`, sequential).
+They are **applied manually** — CI and the Vercel deploy do **not** run them.
+Never edit an already-applied migration; always add a new numbered file.
+Helper scripts live in `scripts/` (e.g. `run-migration.ts`, `test-db-connection.ts`).
+
+## Deploy path
+
+- Push / merge to `main` → GitHub Actions runs `npm run verify`, then deploys to
+  **Vercel production**.
+- Pull requests → `verify` runs and a Vercel **preview** deploy is created.
+- Prod only receives commits that passed CI (the local `.husky/pre-push` hook is
+  CI-gated for the parallel Hetzner mirror).
+
+## Security
+
+This repo has a history of leaked keys. Never commit real secrets. Only
+`.env.example` holds placeholder values; real values live in Vercel env settings
+and local `.env*` files (git-ignored). Do not print secret values in logs or PRs.
+
+## Conventions
+
+Follow `.claude/CLAUDE.md` and the imported global standards: SSOT, DRY, SoC,
+TypeScript strict, no hardcoded secrets, no `console.log` in production, semantic
+Tailwind classes over inline styles.
diff --git a/package.json b/package.json
index f1b64c45..9e231e3e 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
     "lint:fix": "next lint --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "verify": "npm run format:check && npm run lint && npm run test && npm run build",
     "prepare": "husky install",
     "lint-staged": "lint-staged"
   },