@next-friday/create-app 6.0.0 → 6.0.2

package/dist/main.mjs

@@ -81,12 +81,15 @@ async function writeEnvironmentFile(directory) {
 */
 function initGit(directory) {
 	if (existsSync(path.join(directory, ".git"))) return "existing";
+	const environment = projectGitEnvironment();
 	if (spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
 		cwd: directory,
+		env: environment,
 		stdio: "ignore"
 	}).status === 0) return "parent";
 	return spawnSync("git", ["init", "--initial-branch=main"], {
 		cwd: directory,
+		env: environment,
 		stdio: "ignore"
 	}).status === 0 ? "initialized" : "failed";
 }
@@ -99,9 +102,22 @@ function didInstallDependencies(directory) {
 	return spawnSync("pnpm install", {
 		cwd: directory,
 		stdio: "inherit",
-		shell: true
+		shell: true,
+		env: projectGitEnvironment()
 	}).status === 0;
 }
+/**
+* The environment without the repository variables that `git rev-parse --local-env-vars` lists.
+* An inherited `GIT_DIR`, as Git sets for its hooks, would point Git, and the install's Git hook
+* setup, at another repository. `git -c` options stay, as Git keeps them for another repository.
+* @returns Environment for commands that run Git in the project directory.
+*/
+function projectGitEnvironment() {
+	const localVariables = new Set(spawnSync("git", ["rev-parse", "--local-env-vars"], { encoding: "utf8" }).stdout?.split("\n"));
+	localVariables.delete("GIT_CONFIG_PARAMETERS");
+	localVariables.delete("GIT_CONFIG_COUNT");
+	return Object.fromEntries(Object.entries(process.env).filter(([name]) => !localVariables.has(name)));
+}
 // src/project-name.ts
 const packageNamePattern = /^[a-z0-9][a-z0-9._-]*$/;
 const maxPackageNameLength = 214;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-friday/create-app",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "Create a Next Friday project from a template.",
   "keywords": [
     "create",

package/templates/base/.agents/hooks/agent-production-gate.sh

@@ -1,10 +1,48 @@
-#!/bin/bash
-# Production deploys require a named release authorization
-cmd=$(jq -r '.tool_input.command // .command' < /dev/stdin)
-if [[ "$cmd" == *"deploy"* && "$cmd" == *"production"* ]]; then
-  if [ -z "$RELEASE_APPROVAL" ]; then
-    echo "Production deploys need a release authorization." >&2
-    exit 2 # exit 2 blocks the action; the message goes to Claude
-  fi
+#!/usr/bin/env bash
+set -uo pipefail
+
+allow() {
+  printf '%s\n' '{"permission":"allow"}'
+  exit 0
+}
+
+block() {
+  jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
+  printf 'agent-production-gate: %s\n' "$1" >&2
+  exit 2
+}
+
+trap 'block ".agents/hooks/agent-production-gate.sh failed. Stop and report this error to the user; agents may not edit the gate."' ERR
+command -v jq > /dev/null || block "jq is required to read the hook input. Install it: https://jqlang.org/download/"
+command=$(jq -r '.command // .tool_input.command // empty')
+[[ -n $command && -z ${RELEASE_APPROVAL:-} ]] || allow
+
+release_gate="A release manager runs prod deploys, commands against prod, and release tag pushes. Do not run this; report what is ready to promote, such as the commit SHA. If a gated command appears only inside a message, write the text to a file and pass it with git commit -F <file> or gh pr create --body-file <file>."
+
+# The gate reads the command line as text, joining continued lines and dropping quotes,
+# backslashes, and fd redirections, so wrappers such as bash -c, eval, or npx and split words such
+# as pr''od do not hide the common forms. A dispatch input or Railway environment the gate cannot
+# read (a variable, a command substitution, a file, or stdin) counts as prod. It is a convenience,
+# not a security boundary: the prod environment's required reviewers and Railway credentials are.
+text=${command//'\\'/}
+text=${text//$'\\\n'/}
+text=$(sed -E 's/([0-9]*[<>]&[0-9-]*|&>>?)//g' <<< "${text//[\"\'\\]/}")
+simple=$'[^;&|\n]*'
+prod="(prod([^[:alnum:]_-]|$)|[\$\`@])"
+dispatch="(workflow[[:space:]]+run|/dispatches)"
+environment_field="environment[]]*[=:][[:space:]]*$prod"
+unreadable_inputs="--(json|input)([[:space:]=]|$)"
+railway="(^|[^[:alnum:]_.-])(railway|@railway/cli(@[^[:space:]]*)?)([[:space:]]$simple)?"
+git_push="(^|[^[:alnum:]_.-])git([[:space:]]+(-[Cc][[:space:]]+[^[:space:]]+|--(git-dir|work-tree|namespace|config-env)[[:space:]]+[^[:space:]]+|--?[^[:space:]]+))*[[:space:]]+push([[:space:]]$simple)?"
+tag_ref="([[:space:]:+]((refs/)?tags/|v[0-9])|[[:space:]]--((follow-)?tags|mirror)([[:space:]=]|$))"
+
+if [[ $text =~ $dispatch$simple($environment_field|$unreadable_inputs) || $text =~ $environment_field$simple$dispatch ]]; then
+  block "$release_gate"
 fi
-exit 0
+if [[ $text =~ $railway[[:space:]](-[[:alpha:]]*e([[:space:]]+|=)?|--environment([[:space:]]+|=))$prod || $text =~ $railway[[:space:]](env|environment)([[:space:]]+[[:alpha:]]+)?[[:space:]]+$prod ]]; then
+  block "$release_gate"
+fi
+if [[ $text =~ $git_push$tag_ref || $(tr '[:upper:]' '[:lower:]' <<< "$text") == *push.followtags* ]]; then
+  block "$release_gate"
+fi
+allow

package/templates/base/.claude/settings.json

@@ -76,7 +76,8 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.agents/hooks/agent-production-gate.sh",
-            "timeout": 10
+            "timeout": 10,
+            "onFailure": "block"
           }
         ]
       },

package/templates/base/.cursor/hooks.json

@@ -29,7 +29,8 @@
       },
       {
         "command": ".agents/hooks/agent-production-gate.sh",
-        "timeout": 10
+        "timeout": 10,
+        "failClosed": true
       }
     ],
     "beforeMCPExecution": [

package/templates/base/SETUP.md

@@ -9,7 +9,7 @@ This project follows Anthropic's [AI-native SDLC Playbook](https://claude.com/re
 3. **Build:** the engineer starts in plan mode, approves the plan, and commits it as `plan.md`. A tech lead approves higher-risk plans.
 4. **Test:** the session runs **Verifying your work** in `AGENTS.md`.
 5. **Review:** Claude Code Review and Bugbot review by `REVIEW.md`. A code owner approves; the agent never does.
-6. **Deploy:** `agent-production-gate.sh` gates production.
+6. **Deploy:** once `DEPLOY_ENABLED` is `true`, each push to `main` that passes CI deploys to `dev`, and the Deploy workflow promotes a commit to `uat` and then `prod`. `agent-production-gate.sh` blocks an agent's shell commands that deploy to `prod`, run a Railway command with `prod` as its environment, or push a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set.
 7. **Maintain:** larger work becomes a new `intent.md`.
 
 ## 1. First commit and push
@@ -94,7 +94,7 @@ Also replace the owner placeholder in `.github/zizmor.yml`.
 - **Sources of truth (engineering lead):** for each artifact, name one system as the source of truth: this repository, an existing tool such as Jira, or, as the minimum, a link both ways (the record id in the file and the commit SHA in the record).
 - **Higher risk (engineering lead):** decide which changes count as higher risk. A tech lead or architect approves their specs and plans.
 - **Policies (each policy owner, with an engineer):** write the policy in `.agents/skills/<area>-policy/SKILL.md` from the owner's source of truth, then run `pnpm rules:sync`. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time. The policy owner approves every later change as its code owner.
-- **Production gate (engineering leadership, with change management and compliance):** list the approvals that must survive. A person then changes `.agents/hooks/agent-production-gate.sh` to match this project's production deploy command and approval; agent settings deny the file to agents.
+- **Production gate (engineering leadership, with change management and compliance):** name the release managers and add them as required reviewers on the `prod` environment, as the README's deploy section describes. `.agents/hooks/agent-production-gate.sh` blocks an agent's shell commands that dispatch a `prod` deploy, run a Railway command with `prod` as its environment, or push a release tag. It does not read MCP tools. A release manager whose own agent session must do one of these starts the agent with `RELEASE_APPROVAL` set to the approval record, for example `RELEASE_APPROVAL=CHG-123 claude`.
 - **Review (tech lead):** replace `src/gen/` in `.agents/review.md` with this project's generated paths, then run `pnpm rules:sync`, which renders it to `REVIEW.md` for Claude Code Review. Once a month, rate the review findings and tune `.agents/review.md`.
 - **People without Git experience:** connect GitHub to Claude (claude.ai or Cowork), so Claude commits `intent.md` for them.
 

package/templates/base/intent/README.md

@@ -6,3 +6,18 @@ This folder is the intent home. Every change starts here as an `intent.md`, and
 - **Plan.** An idea, a ticket, or an incident becomes `intent.md`, written with the `write-intent` skill. The product owner reviews and corrects it before it is committed. Merging its pull request records the decision: `Status: accepted.` accepts it, and `Status: rejected.` rejects it.
 - **Design.** The `write-spec` skill turns the accepted `intent.md` into `spec.md`, committed alongside it. The product owner reviews the spec against the idea and resolves each area of concern with its policy owner. Accepting the spec starts the build.
 - **Build.** The engineer starts in plan mode with `intent.md` and `spec.md`, and commits the approved plan as `plan.md`. When implementation departs from the plan, `plan.md` changes in the same commit.
+
+## Which file holds what
+
+The bullets above say who writes and who decides each file. What each file answers:
+
+| File        | Answers                                                                                                    |
+| :---------- | :--------------------------------------------------------------------------------------------------------- |
+| `intent.md` | The problem, the outcome wanted, the users and systems it affects, its constraints, and its open questions |
+| `spec.md`   | What to build and how it is designed: requirements, design, and areas of concern                           |
+| `plan.md`   | How to make the change: the files that change, the order of the work, and the tests that prove it          |
+
+## Where a technology choice goes
+
+- **A choice already made**, such as a required framework or service, goes into the intent's **Constraints**. The spec designs within it.
+- **A choice to weigh**, such as two libraries or two approaches, goes into the intent's **Proposed outcome** as a proposal or into its **Open questions**. The spec compares the options in its design, with sources, and the product owner accepts or corrects the choice in review.

package/templates/base/scripts/check-agent-gates.ts

@@ -6,12 +6,14 @@ type GateCase = {
   gate: string;
   input: Record<string, unknown>;
   name: string;
+  releaseApproval?: string;
 };
 
 const shellGate = ".agents/hooks/agent-shell-gate.sh";
 const suppressionGate = ".agents/hooks/agent-suppression-gate.sh";
 const constitutionGate = ".cursor/hooks/agent-constitution-gate.sh";
 const mcpGate = ".agents/hooks/agent-mcp-gate.sh";
+const productionGate = ".agents/hooks/agent-production-gate.sh";
 const sourceFile = "src/example.ts";
 
 const blockedCommands = [
@@ -189,6 +191,101 @@ const allowedCommands = [
   'gh api repos/next-friday/example/issues/1/comments -f body="APPROVED by QA"',
 ];
 
+const productionCommands = [
+  "gh workflow run deploy.yml -f environment=prod -f commit_sha=abc",
+  "gh workflow run Deploy --field 'environment=prod'",
+  "gh workflow run deploy.yml -fenvironment=prod",
+  "gh workflow run deploy.yml --field=environment=prod",
+  'gh workflow run deploy.yml -f "environment=prod"',
+  "gh workflow run deploy.yml -F environment=@environment.txt",
+  "gh workflow run deploy.yml --json",
+  "gh workflow run deploy.yml --json=true",
+  "for e in uat prod; do gh workflow run deploy.yml -f environment=$e -f commit_sha=abc; done",
+  "env=prod; gh workflow run deploy.yml -f environment=$env",
+  "gh workflow run deploy.yml -f environment=$(echo prod)",
+  'gh workflow run deploy.yml -f "environment=$TARGET"',
+  "gh api -X POST repos/o/r/actions/workflows/deploy.yml/dispatches -f ref=main -f 'inputs[environment]=prod'",
+  "gh api repos/o/r/actions/workflows/deploy.yml/dispatches/ -f inputs[environment]=prod",
+  "gh api -f 'inputs[environment]=prod' repos/o/r/actions/workflows/deploy.yml/dispatches",
+  "gh api repos/o/r/actions/workflows/1/dispatches --input body.json",
+  "gh api repos/o/r/actions/workflows/1/dispatches -f inputs[environment]=$E",
+  "bash -c 'gh workflow run deploy.yml -f environment=prod'",
+  "railway up --ci --environment prod",
+  "railway up -e prod",
+  "railway up -e=prod",
+  "railway up -eprod",
+  "railway up -ce prod",
+  "railway up -ceprod",
+  "railway redeploy -ye prod",
+  "railway up -s api -e prod",
+  "railway up --environment=prod",
+  'railway up -e "$ENV"',
+  "for e in uat prod; do railway up -e $e; done",
+  "railway env prod",
+  "railway env link prod",
+  "railway environment prod",
+  "railway environment delete prod --yes",
+  "railway link -e prod",
+  "railway logs -e prod",
+  "railway variables --set A=b -e prod",
+  "npx @railway/cli up -e prod",
+  "pnpm dlx @railway/cli up -e prod",
+  "/usr/local/bin/railway up -e prod",
+  "timeout 60 railway up -e prod",
+  "eval railway up -e prod",
+  "git push origin v1.0.0",
+  "git push origin HEAD:refs/tags/v1.0.0",
+  "git push --tags",
+  "git push --follow-tags origin main",
+  "git -C . push origin v2.3.4",
+  "npx @railway/cli@5.71.0 up -e prod",
+  "npx @railway/cli@latest up --environment prod",
+  "railway up -e pr''od",
+  "gh workflow run deploy.yml -f environment=pr''od",
+  "gh workflow run deploy.yml -f environment=p\\rod",
+  'gh workflow run deploy.yml -f "envi"ronment=prod',
+  "git push origin 'refs/tags/*'",
+  'git push origin "refs/tags/v*"',
+  "git push --mirror",
+  "git -c push.followTags=true push origin main",
+  "git config push.followTags true && git push",
+  "gh workflow run deploy.yml 2>&1 -f environment=prod",
+  "railway up 2>&1 -e prod",
+  "git push origin tags/v1.0.0",
+  "git --git-dir .git push origin v1.0.0",
+  "gh workflow run deploy.yml \\\n  -f environment=prod \\\n  -f commit_sha=abc",
+  "railway up \\\n  --environment prod",
+  "git push \\\n  origin v1.0.0",
+  "railway up &>/dev/null -e prod",
+  "git push &>/dev/null origin v1.0.0",
+  "cd a\\\\\ngit push origin v1.0.0",
+];
+
+const nonProductionCommands = [
+  "gh workflow run deploy.yml -f environment=uat -f commit_sha=abc",
+  "gh api repos/o/r/actions/workflows/deploy.yml/dispatches -f 'inputs[environment]=uat'",
+  "railway up -e uat",
+  "railway up -e prod-eu",
+  "railway environment uat",
+  "railway status",
+  "gh workflow list",
+  "gh run list --workflow deploy.yml",
+  "gh api repos/o/r/environments/prod",
+  "git push -u origin feature/v2-ui",
+  "git push origin main",
+  'git commit -m "release v1.0" && git push',
+  'git commit -m "docs(x): deploy to production"',
+  'gh pr create --title "ci(x): promote to prod" --body "run gh workflow run later"',
+  "echo railway",
+  "git tag v1.0.0",
+  'git stash push -m "wip v2"',
+  'git commit -m "fix(ci): push v2 images"',
+  'git commit -m "fix: railway env uat and prod split"',
+  "git push -u origin HEAD",
+  "git push origin feature/push-v2",
+  "pnpm verify 2>&1 | tail && git push",
+];
+
 const mcpTools = {
   blocked: [
     "mcp__github__merge_pull_request",
@@ -273,6 +370,47 @@ const cases: GateCase[] = [
     expectedPermission: "allow" as const,
     name: `shell: ${command}`,
   })),
+  ...productionCommands.flatMap(command => [
+    {
+      gate: productionGate,
+      input: {
+        command,
+      },
+      expectedExit: 2 as const,
+      name: `Cursor production: ${command}`,
+    },
+    {
+      gate: productionGate,
+      input: {
+        tool_input: {
+          command,
+        },
+      },
+      expectedExit: 2 as const,
+      name: `Claude production: ${command}`,
+    },
+  ]),
+  {
+    gate: productionGate,
+    releaseApproval: "CHG-1",
+    expectedPermission: "allow",
+    name: "production with RELEASE_APPROVAL: railway up -e prod",
+    expectedExit: 0,
+    input: {
+      tool_input: {
+        command: "railway up -e prod",
+      },
+    },
+  },
+  ...nonProductionCommands.map(command => ({
+    gate: productionGate,
+    input: {
+      command,
+    },
+    expectedExit: 0 as const,
+    expectedPermission: "allow" as const,
+    name: `production: ${command}`,
+  })),
   ...mcpTools.blocked.map(tool => ({
     gate: mcpGate,
     input: {
@@ -399,6 +537,7 @@ const failures = cases.filter(gateCase => {
       ...process.env,
       CLAUDE_PROJECT_DIR: process.cwd(),
       CURSOR_PROJECT_DIR: process.cwd(),
+      RELEASE_APPROVAL: gateCase.releaseApproval,
     },
     input: JSON.stringify(gateCase.input),
   });

package/templates/nestjs/AGENTS.md

@@ -43,6 +43,7 @@ If a test fails, fix the code, not the test.
 When Claude makes a mistake twice, add the correction here.
 
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
 
 ## Related documentation
 

package/templates/nestjs/README.md

@@ -53,7 +53,7 @@ On Vercel, the zero-configuration NestJS preset takes precedence over the `Docke
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/nextjs/AGENTS.md

@@ -44,6 +44,7 @@ When Claude makes a mistake twice, add the correction here.
 
 - **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
 
 ## Related documentation
 

package/templates/nextjs/README.md

@@ -49,7 +49,7 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/nodejs/AGENTS.md

@@ -41,6 +41,7 @@ If a test fails, fix the code, not the test.
 When Claude makes a mistake twice, add the correction here.
 
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
 
 ## Related documentation
 

package/templates/nodejs/README.md

@@ -49,7 +49,7 @@ docker run --env PORT=3000 --publish 3000:3000 app
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/payload/AGENTS.md

@@ -47,6 +47,7 @@ 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`.
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
 
 ## Related documentation
 

package/templates/payload/README.md

@@ -73,7 +73,7 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/turborepo/AGENTS.md

@@ -50,6 +50,7 @@ When Claude makes a mistake twice, add the correction here.
 - **Next.js docs live per app**: this Next.js version differs from your training data. Read the guide in `apps/app/node_modules/next/dist/docs/` or `apps/backoffice/node_modules/next/dist/docs/` before writing Next.js code; the workspace root has no `next` package.
 - **Database for `pnpm dev` and end-to-end tests**: the backoffice needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first `pnpm test:e2e`.
 - **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It also blocks merging or approving a pull request, approving a deployment, and gh aliases, and asks the person before an irreversible git command such as a force push or a hard reset. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` (`gh workflow run` or a workflow dispatch with `environment=prod`), a Railway CLI command that names `prod` with `-e`, `--environment`, or `railway environment`, and a release tag push, 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. It is a convenience, not a security boundary: the `prod` environment's required reviewers and Railway credentials are the boundary.
 
 ## Related documentation
 

package/templates/turborepo/README.md

@@ -79,7 +79,7 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
    - the `APP_URL` variable: the public Next.js `https://` URL;
    - the `BACKOFFICE_URL` variable: the public backoffice `https://` URL.
 
-   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch. Add the release managers as required reviewers on `prod` only; `dev` deploys on every push to `main`, so a reviewer there would hold each push. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`. The workflow compares the commit with the last GitHub deployment to that environment and runs `railway up` only for services whose packages changed. A promotion through `uat` or `prod` uses the same comparison against the commit last deployed there, so several commits still ship every changed service. The first deploy to an environment ships both services.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health` on each service it uploaded.