@next-friday/create-app 9.1.1 → 9.2.1

package/templates/nodejs/package.json

@@ -2,7 +2,7 @@
   "name": "next-friday-template-nodejs",
   "version": "0.1.0",
   "private": true,
-  "description": "Next Friday Node.js template.",
+  "description": "Node.js HTTP service without a framework.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/next-friday/next-friday-template-nodejs.git"
@@ -11,44 +11,45 @@
   "author": "Next Friday",
   "type": "module",
   "scripts": {
+    "bands:check": "node scripts/check-bands.ts",
     "build": "tsc -p tsconfig.build.json",
     "check": "pnpm verify:static && pnpm test:changed && pnpm build",
-    "clean": "rm -rf dist coverage *.tsbuildinfo .eslintcache node_modules/.cache",
+    "clean": "rm -rf dist coverage .eslintcache node_modules/.cache",
     "depcruise": "depcruise --config .dependency-cruiser.json src eslint.config.ts vitest.config.ts",
+    "evals:run": "node scripts/run-agent-evals.ts",
     "format": "prettier --write --cache .",
     "format:check": "prettier --check --cache . && editorconfig-checker",
     "gates:check": "node scripts/check-agent-gates.ts",
-    "human-gates:check": "node scripts/check-human-gates.ts",
-    "intent:check": "node scripts/check-intent.ts",
     "knip": "knip",
     "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
     "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
-    "peers:check": "pnpm peers check",
+    "loop:measure": "node scripts/measure-loop.ts",
+    "plan:check": "node scripts/check-plan.ts",
     "prepare": "husky",
     "rules:check": "node scripts/sync-agent-rules.ts --check",
     "rules:sync": "node scripts/sync-agent-rules.ts",
     "sort-package-json": "sort-package-json package.json",
     "sort-package-json:check": "sort-package-json --check package.json",
-    "start": "node --env-file-if-exists=.env dist/main.js",
+    "start": "pnpm build && node --env-file-if-exists=.env dist/main.js",
     "start:dev": "node --env-file-if-exists=.env --watch src/main.ts",
     "start:prod": "node dist/main.js",
-    "suppressions:check": "bash .agents/hooks/agent-suppression-gate.sh --repo",
     "test": "vitest run --passWithNoTests",
     "test:changed": "if git rev-parse --quiet --verify origin/main > /dev/null && git diff --quiet \"$(git merge-base origin/main HEAD)\" -- pnpm-lock.yaml pnpm-workspace.yaml \"*package.json\" \"*tsconfig.json\" .husky; then vitest run --changed origin/main --passWithNoTests; else vitest run --passWithNoTests; fi",
     "test:coverage": "vitest run --coverage --passWithNoTests",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "verify": "pnpm verify:static && pnpm test:coverage && pnpm build",
-    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm intent:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+    "verify:static": "pnpm rules:check && pnpm gates:check && pnpm plan:check && pnpm bands:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm knip && pnpm depcruise"
   },
   "devDependencies": {
     "@commitlint/cli": "21.2.4",
     "@next-friday/commitlint-config-friday": "4.0.0",
     "@next-friday/eslint-config-friday": "5.1.0",
     "@next-friday/prettier-config-friday": "4.0.0",
+    "@swc/core": "1.16.22",
     "@types/node": "26.6.6",
-    "@vitest/coverage-v8": "5.0.5",
-    "dependency-cruiser": "18.7.1",
+    "@vitest/coverage-v8": "5.1.0",
+    "dependency-cruiser": "18.7.2",
     "editorconfig-checker": "7.0.0",
     "eslint": "10.14.0",
     "fast-check": "4.10.2",
@@ -59,7 +60,8 @@
     "prettier": "3.9.10",
     "sort-package-json": "4.1.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0",
+    "yaml": "2.9.1"
   },
   "packageManager": "pnpm@12.6.0+sha512.3ef68f951cb111ac204b4a5a16f0b2ddf0da56a96e0413e81d855d9f0b55ef926714709028e1cd00c405c2c5fb7b9e8ec4dc46777c805d0373c2f2ff00fd20ec",
   "engines": {

package/templates/nodejs/src/server.test.ts

@@ -1,3 +1,4 @@
+import {connect} from "node:net";
 import {describe, expect, it} from "vitest";
 import {once} from "node:events";
 import type {AddressInfo} from "node:net";
@@ -57,4 +58,26 @@ describe("createAppServer", () => {
 
     expect(response.status).toBe(404);
   });
+
+  it("returns 404 for a request target that is not a valid URL", async () => {
+    const server = createAppServer();
+
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+
+    const {port} = server.address() as AddressInfo;
+    const socket = connect(port, "127.0.0.1");
+
+    socket.end("GET // HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n");
+
+    const chunks: Buffer[] = [];
+
+    for await (const chunk of socket) {
+      chunks.push(chunk as Buffer);
+    }
+
+    server.close();
+    await once(server, "close");
+    expect(Buffer.concat(chunks).toString()).toMatch(/^HTTP\/1\.1 404 /);
+  });
 });

package/templates/nodejs/src/server.ts

@@ -2,12 +2,12 @@ import {createServer} from "node:http";
 import type {Server} from "node:http";
 
 /**
- * Create the HTTP server. `GET` or `HEAD` `/health` reports that the process is up; every other request gets 404.
+ * Create the HTTP server. `GET` or `HEAD` `/health` reports that the process is up; every other request, including one whose target is not a valid URL, gets 404.
  * @returns A server that is not listening yet.
  */
 export function createAppServer(): Server {
   return createServer((request, response) => {
-    const {pathname} = new URL(request.url ?? "/", "http://localhost");
+    const pathname = URL.parse(request.url ?? "/", "http://localhost")?.pathname;
 
     if (pathname === "/health" && (request.method === "GET" || request.method === "HEAD")) {
       response.writeHead(200, {

package/templates/nodejs/tsconfig.build.json

@@ -1,9 +1,8 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "rootDir": "./src",
-    "types": ["node"]
+    "rootDir": "./src"
   },
   "include": ["src"],
-  "exclude": ["node_modules", "test", "dist", "**/*.test.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }

package/templates/nodejs/tsconfig.json

@@ -4,14 +4,10 @@
     "module": "nodenext",
     "isolatedModules": true,
     "removeComments": true,
-    "incremental": true,
-    "resolveJsonModule": true,
     "skipLibCheck": true,
-    "sourceMap": true,
     "outDir": "./dist",
     "rootDir": ".",
     "types": ["node"],
-    "strict": true,
     "rewriteRelativeImportExtensions": true
   },
   "include": ["**/*.ts"],

package/templates/payload/.agents/agents/verifier.md

@@ -1 +1 @@
-Start the app with `pnpm dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.
+Start the app with `pnpm dev`, which needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/payload/.agents/review.md

@@ -0,0 +1,21 @@
+# Review instructions
+
+## Passes
+
+Run three passes and tag each finding with its pass:
+
+- Bugs: logic errors, broken edge cases, subtle regressions
+- Security: injection risks, authentication gaps, PII in logs
+- Compliance: the change matches spec.md, plan.md and the design principles that the four policies in `.agents/skills/` state; flag a plan.md that has no `Accepted by:` line and a change that makes `AGENTS.md` outdated
+
+## What Important means here
+
+Reserve Important for findings that would break behavior, leak data or breach a policy. Style and naming are nits.
+
+## Cap the nits
+
+Report at most five nits per review; summarize the rest as a count.
+
+## Do not report
+
+Generated files and anything CI already enforces: `pnpm-lock.yaml`, `src/app/(payload)/**`, `src/migrations/**`, and `src/payload-types.ts`.

package/templates/payload/.claude/agents/verifier.md

@@ -4,4 +4,4 @@ description: Runs the app and checks the change works before the session reports
 tools: Bash, Read
 ---
 
-Start the app with `pnpm dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.
+Start the app with `pnpm dev`, which needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/payload/.cursor/agents/verifier.md

@@ -4,4 +4,4 @@ description: Runs the app and checks the change works before the session reports
 readonly: true
 ---
 
-Start the app with `pnpm dev`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.
+Start the app with `pnpm dev`, which needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.

package/templates/payload/.dependency-cruiser.json

@@ -20,8 +20,8 @@
     }
   ],
   "options": {
+    "parser": "swc",
     "skipAnalysisNotInRules": true,
-    "tsPreCompilationDeps": true,
     "enhancedResolveOptions": {
       "conditionNames": ["import", "require", "node", "default", "types"],
       "exportsFields": ["exports"]

package/templates/payload/.github/ISSUE_TEMPLATE/bug.yml

@@ -21,7 +21,7 @@ body:
     id: version
     attributes:
       label: Commit
-      placeholder: 769e0ef
+      placeholder: Output of `git rev-parse --short HEAD`
     validations:
       required: true
   - type: textarea

package/templates/payload/.github/workflows/ci.yml

@@ -90,16 +90,14 @@ jobs:
         with:
           cache: true
           require-lockfile: true
-      - name: Reject suppression directives
-        run: pnpm suppressions:check
-      - name: Check Cursor rules match .agents/rules
+      - name: Check rendered agent rules match .agents/rules
         run: pnpm rules:check
       - name: Check agent gates
         run: pnpm gates:check
-      - name: Check human gates
-        run: pnpm human-gates:check
-      - name: Self-test the intent checker
-        run: pnpm intent:check
+      - name: Check plans
+        run: pnpm plan:check
+      - name: Check bands
+        run: pnpm bands:check
       - name: Check lint
         run: pnpm lint:check
       - name: Check formatting
@@ -108,8 +106,6 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }} # editorconfig-checker downloads its binary from GitHub releases; the token avoids the anonymous rate limit.
       - name: Check package.json ordering
         run: pnpm sort-package-json:check
-      - name: Validate peer dependency contracts
-        run: pnpm peers:check
       - name: Check types
         run: pnpm typecheck
       - name: Run Knip
@@ -143,7 +139,23 @@ jobs:
     if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    services:
+      postgres:
+        image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: payload
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready --username postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
     env:
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/payload
+      PAYLOAD_SECRET: ci-only-secret
+      APP_URL: http://localhost:3000
       HADOLINT_VERSION: 2.15.1
       HADOLINT_SHA256: c7187db94eeeeca956519a6af171adc31453941a1e777961f6e680f697c8c507
       TRIVY_VERSION: 0.76.1
@@ -165,7 +177,7 @@ jobs:
       - name: Smoke test image
         id: smoke
         run: |
-          docker run --detach --name app --env PORT=3000 --publish 3000:3000 app:ci
+          docker run --detach --name app --network host --env PORT=3000 --env DATABASE_URL --env PAYLOAD_SECRET --env APP_URL app:ci
           curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
       - name: Show container logs
         if: failure() && steps.smoke.outcome == 'failure'
@@ -193,6 +205,59 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  triage:
+    name: Triage failed build
+    needs:
+      - changes
+      - checks
+      - image
+    if: failure() && vars.CLAUDE_CI_ENABLED == 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      actions: read # Needed to read the logs of the failed jobs.
+      id-token: write # Needed to authenticate the Claude GitHub App with the workflow's OIDC token.
+      pull-requests: write # Needed to post the summary on the pull request.
+    steps:
+      - name: Require a Claude credential
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          [[ -n "$ANTHROPIC_API_KEY" || -n "$CLAUDE_CODE_OAUTH_TOKEN" ]] || { echo "::error::Set the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY repository secret"; exit 1; }
+      - name: Collect the build log
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          mkdir -p out
+          for job in $(gh api "repos/$REPOSITORY/actions/runs/$RUN_ID/jobs" --paginate --jq '.jobs[] | select(.conclusion == "failure") | .id'); do
+            gh api --allow-escape-sequences "repos/$REPOSITORY/actions/jobs/$job/logs" >> out/build.log
+          done
+      - name: Triage failed build
+        id: triage
+        uses: anthropics/claude-code-action@61a9c274fa7110a66dfafc1bbbced03833eb25fe # v1.0.269
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: >
+            Read the build log at out/build.log. Identify the most
+            likely cause, say whether the failure looks flaky or real, and write a
+            three-line summary for the PR thread.
+          claude_args: >-
+            --model claude-haiku-5-5
+            --max-turns 5
+            --allowedTools "Read"
+            --json-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}'
+      - name: Post the summary
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPOSITORY: ${{ github.repository }}
+          SUMMARY: ${{ fromJSON(steps.triage.outputs.structured_output).summary }}
+        run: gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body "$SUMMARY"
+
   ci:
     name: All Checks
     if: always()

package/templates/payload/.github/workflows/sast.yml

@@ -5,11 +5,6 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - "**/*.md"
-      - ".agents/**"
-      - ".claude/**"
-      - ".cursor/**"
   schedule:
     - cron: "17 2 * * 1"
 

package/templates/payload/AGENTS.md

@@ -4,49 +4,53 @@ Payload CMS on Next.js App Router and PostgreSQL, in TypeScript on pnpm and Node
 
 ## Commands
 
-| Task                          | Command                                                    |
-| :---------------------------- | :--------------------------------------------------------- |
-| Start with reload             | `pnpm dev`                                                 |
-| One test                      | `pnpm vitest run src/environment.test.ts -t "<test name>"` |
-| Unit tests                    | `pnpm test`, or `pnpm test:coverage`                       |
-| End-to-end tests              | `pnpm test:e2e`                                            |
-| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap`           |
-| Create a migration            | `pnpm migrate:create <name>`                               |
-| What `pre-push` runs          | `pnpm check`                                               |
-| Every check                   | `pnpm verify`                                              |
-| Render rules after a change   | `pnpm rules:sync`                                          |
+| Task                               | Command                                                    | Healthy output                                                                                                               |
+| :--------------------------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| Start with reload                  | `pnpm dev`                                                 | `✓ Ready in 251ms`                                                                                                           |
+| One test                           | `pnpm vitest run src/environment.test.ts -t "<test name>"` | `Tests  1 passed \| 2 skipped (3)`                                                                                           |
+| Unit tests                         | `pnpm test`, or `pnpm test:coverage`                       | `Tests  13 passed (13)`                                                                                                      |
+| End-to-end tests                   | `pnpm test:e2e`                                            | `2 passed (9.4s)`, with `DATABASE_URL` pointing at a running database                                                        |
+| Regenerate after a collection      | `pnpm generate:types`, `pnpm generate:importmap`           | `INFO: Compiling TS types for Collections and Globals...`, then nothing; `No new imports found, skipping writing import map` |
+| Create a migration                 | `pnpm migrate:create <name>`                               | `INFO: Migration created at` the new file under `migrations/`, then `INFO: Done.`                                            |
+| What `pre-push` runs               | `pnpm check`                                               | exits 0; the last output is the route table of `next build` with `ƒ /health`                                                 |
+| Every check except `pnpm test:e2e` | `pnpm verify`                                              | exits 0; the last output is the route table of `next build` with `ƒ /health`                                                 |
+| Render rules after a change        | `pnpm rules:sync`                                          | `Synced 69 agent rule files; 0 updated.`                                                                                     |
 
 ## Verifying your work
 
 - Build: `pnpm build` (prints the `Route (app)` table)
 - Test: `pnpm test:coverage` (all green, then the coverage summary; never skip or delete a failing test)
-- Lint: `pnpm verify:static` (ESLint allows zero warnings; prints `✔ no dependency violations found`)
+- Static checks: `pnpm verify:static` (ESLint allows zero warnings; every check must pass)
 
 Run all three before reporting any task complete, and paste the output. `pnpm verify` runs all three.
 
 ## Architecture
 
-- `src/payload.config.ts` wires the collections in `src/collections/` to PostgreSQL. The site lives in `src/app/(frontend)/`, and `src/app/health/route.ts` serves `/health`.
-- In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `src/migrations/` when it starts.
+- `src/payload.config.ts` wires the collections in `src/collections/` to PostgreSQL. The site lives in `src/app/(frontend)/`, and `src/app/health/route.ts` serves `/health`. `next.config.ts` builds `output: "standalone"` and leaves Cache Components off.
+- In development, Payload applies collection changes to the database directly. In production, Payload applies the migrations in `src/migrations/` when it first initialises, which `/health` triggers, so the first health check after a deploy applies them, not when the server starts.
 
 ## Conventions
 
-1. **Change the schema only through collections, then regenerate and commit.** Payload generates `src/app/(payload)/`, `src/payload-types.ts`, and `src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
+1. **Change the schema only through collections, then regenerate and commit.** Payload generates `src/payload-types.ts`, `src/migrations/`, and `src/app/(payload)/admin/importMap.ts`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
 2. **Put unit tests next to the code as `src/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
 3. **Component tests need a DOM test environment, and Vitest runs in Node.js.** Add that environment with the first component test.
 4. **Read configuration through `requireEnvironment` in `src/environment.ts`.** Document each variable in `.env.example`.
 5. **Start from the accepted spec, in plan mode** (Cursor: Plan Mode). Give the plan the change's `intent/<change>/intent.md` and `spec.md`. Commit the approved plan as `intent/<change>/plan.md` with an `Accepted by:` line naming the engineer, as `.agents/skills/sdlc/playbooks/build.md` describes.
-6. **Start a bug fix with a failing test.** Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, make the test pass without editing it, and delete `.git/bug-fix-in-progress`.
+6. **Start a bug fix with a failing test.** A bug fix has no intent and no spec; its plan, `intent/<short-description>/plan.md`, is accepted by an engineer before any code changes. Reproduce the bug as a test, confirm it fails for the reason you expect, and commit it on a `fix/` branch. Then `.agents/hooks/agent-test-edit-gate.sh` blocks test edits by itself: make the test pass without editing it. On a branch with another name, create `.git/bug-fix-in-progress` first, and delete it once the test passes.
 7. **Do not start work a person did not ask for.** When a message reports a problem without asking for work, answer in a few lines and end with the message that would start it: `/sdlc` followed by their own words.
 8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
-9. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
+9. **Write replies a person can check.** Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
+10. **Run parallel sessions in separate worktrees, on tasks that touch different files.** Start each with `claude --worktree <name>`: a worktree is its own checkout on its own branch. Tasks that share files run in one session, one after another. Start with two or three sessions, and add one only while you can review every stream properly.
 
 ## Things Claude gets wrong
 
 When Claude makes a mistake twice, add the correction here.
 
 - **Database for `pnpm dev` and end-to-end tests**: both need a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
-- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+- **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
+- **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
+- **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/payload/CONTRIBUTING.md

@@ -8,7 +8,7 @@ Use this guide to prepare changes to this repository.
 - Change the Node.js version in `.nvmrc` and the `Dockerfile` together. Dependabot updates only the `Dockerfile`.
 - Install pnpm once with `npm install --global pnpm`. It switches to the version declared by `package.json#packageManager` automatically.
 - Use Claude Code v2.1.295 or later. It reads `CLAUDE.md`, which imports `AGENTS.md`, and supports the `onFailure` field the agent hooks use.
-- Install gitleaks 8.19 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
+- Install gitleaks 8.21 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
 
 From the repository root:
 
@@ -21,7 +21,7 @@ pnpm install
 
 - Fix lint, type, and test failures at their root cause.
 - Put unit tests next to the code as `*.test.ts` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.
-- Change the database schema only through collections, then run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>` and commit the generated files. Production applies pending migrations when the server starts.
+- Change the database schema only through collections, then run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>` and commit the generated files. Production applies pending migrations when Payload first initialises, which `/health` triggers.
 - Treat `coverage/` as generated output.
 - Do not commit `.env` files or credentials.
 
@@ -36,9 +36,10 @@ Run the narrowest check that covers the change while you work. Git hooks run the
 | `pre-merge-commit` | blocks merge commits on `main`                                                                                                                                  |
 | `pre-push`         | blocks pushes to `main` except the push that creates it, then `pnpm check`: the static checks, the unit tests related to your changes, and the production build |
 
-- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. Dependabot and OSV-Scanner report vulnerable dependencies.
+- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, OSV, CodeQL, dependency-review, and OpenSSF Scorecard scans. CodeQL, dependency-review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`. Dependabot and OSV-Scanner report vulnerable dependencies.
 - **End-to-end tests:** run `pnpm test:e2e` when you change pages or the admin panel. It starts the development server unless one is already running, and needs `DATABASE_URL` and `PAYLOAD_SECRET` from `.env`. Run `pnpm exec playwright install chromium` once before the first run. CI runs it against the production build and a PostgreSQL service on every pull request that is ready for review and changes code.
 - **Coverage:** CI requires 95% branch coverage on changed lines in `src/`, except layouts, the Payload config, and generated files.
+- **Agent evals:** run `pnpm evals:run` after you change `AGENTS.md`, a skill under `.agents/skills/`, or a hook under `.agents/hooks/`, and add a case name to run one case. It runs the cases in `.agents/skill-evals/` with Claude Code on your own Claude login, so it spends your Claude usage, and it is not part of `pnpm verify`.
 
 Run `pnpm verify` for repository changes.
 

package/templates/payload/Dockerfile

@@ -1,6 +1,6 @@
 # Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build
 ENV NEXT_TELEMETRY_DISABLED=1
 WORKDIR /app
@@ -14,7 +14,7 @@ COPY src ./src
 RUN PAYLOAD_SECRET=build-only DATABASE_URL=postgres://build-only@localhost/build-only APP_URL=http://localhost:3000 pnpm build
 
 FROM \
-  node@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
+  node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
 ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 HOSTNAME=0.0.0.0
 WORKDIR /app
 # Apply Alpine security fixes released after the base image, and drop npm, corepack, and yarn: the app never runs them, and their bundled dependencies carry their own CVEs.

package/templates/payload/README.md

@@ -1,6 +1,6 @@
 # next-friday-template-payload
 
-Next Friday starter for Payload CMS on Next.js and PostgreSQL. The API is REST at `/api`.
+Payload CMS application on Next.js and PostgreSQL. The API is REST at `/api`.
 
 ## Getting started
 
@@ -20,11 +20,11 @@ Then open `http://localhost:3000/admin` to create the first user.
 
 **Warning:** until the first user exists, anyone who can reach `/admin` can create it. Create the first user in each deployed environment right after its first deploy, before you share the URL.
 
-In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `src/migrations/` when it starts.
+In development, Payload applies collection changes to the database directly. In production, Payload applies the migrations in `src/migrations/` when it first initialises, which `/health` triggers, so the first health check after a deploy applies them and fails while the database is unreachable.
 
 ## After creating a project from this template
 
-Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, and the AI-native SDLC. In step 1, also replace the `Next Friday Payload template` text in `src/app/(frontend)/layout.tsx`, `src/app/(frontend)/page.tsx`, and their tests.
+Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, and the AI-native SDLC. In step 1, also replace the `Payload application` text in `src/app/(frontend)/layout.tsx`, `src/app/(frontend)/page.tsx`, and `src/app/(frontend)/page.test.ts`.
 
 ## Scripts
 
@@ -42,7 +42,9 @@ Follow [SETUP.md](SETUP.md) in order. It sets up the repository, the reviews, an
 | `pnpm check`              | Run the static checks, the unit tests for changed code, and the production build (the `pre-push` hook)            |
 | `pnpm verify`             | Run the static checks, all unit tests with coverage, and the production build                                     |
 
-CI also runs the build, the end-to-end tests, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
+`pnpm build` copies `.env` into `.next/standalone`, where every secret sits in plain text. Keep that folder out of images and archives.
+
+CI also runs the build, the end-to-end tests, the container image scan, and the security scans, including CodeQL, dependency review, and OpenSSF Scorecard. CodeQL, dependency review, and Scorecard run on public repositories, and on private ones when the `CODE_SCANNING` repository variable is `true`.
 
 ## Container
 
@@ -55,6 +57,8 @@ docker run --publish 3000:3000 --env DATABASE_URL --env PAYLOAD_SECRET --env APP
 
 Uploaded images, up to 10 MB each, are written to the container filesystem, which a redeploy discards. Add a Payload storage adapter, for example `@payloadcms/storage-s3`, before storing media in production.
 
+The config sets no `email` adapter, so Payload writes every email, including password-reset links, to the server log. Set `email` in `src/payload.config.ts` before production.
+
 On Vercel, deploy without the image; the Next.js preset takes precedence over the `Dockerfile`.
 
 ## Deploy

package/templates/payload/REVIEW.md

@@ -0,0 +1,21 @@
+# Review instructions
+
+## Passes
+
+Run three passes and tag each finding with its pass:
+
+- Bugs: logic errors, broken edge cases, subtle regressions
+- Security: injection risks, authentication gaps, PII in logs
+- Compliance: the change matches spec.md, plan.md and the design principles that the four policies in `.agents/skills/` state; flag a plan.md that has no `Accepted by:` line and a change that makes `AGENTS.md` outdated
+
+## What Important means here
+
+Reserve Important for findings that would break behavior, leak data or breach a policy. Style and naming are nits.
+
+## Cap the nits
+
+Report at most five nits per review; summarize the rest as a count.
+
+## Do not report
+
+Generated files and anything CI already enforces: `pnpm-lock.yaml`, `src/app/(payload)/**`, `src/migrations/**`, and `src/payload-types.ts`.