@next-friday/create-app 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,252 @@
+import {spawnSync} from "node:child_process";
+
+type GateCase = {
+  expectedExit: 0 | 2;
+  gate: string;
+  input: Record<string, unknown>;
+  name: 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 sourceFile = "src/example.ts";
+
+const blockedCommands = [
+  "git commit -n -m x",
+  "git commit -nm x",
+  "git commit -a -n -m x",
+  "git commit -an",
+  "git commit -m x -n",
+  "git commit --amend -n",
+  "git -C . commit -n",
+  "git commit --no-verify -m x",
+  "git push --no-verify",
+  "HUSKY=0 git commit -m x",
+  "export HUSKY=0; git commit -m x",
+  "git config core.hooksPath /dev/null",
+  "gh repo delete next-friday/example",
+  "gh issue delete 1",
+  "gh release delete v1",
+  "git commit --no-verif -m x",
+  "git commit --no-v -m x",
+  'git commit "--no-verify" -m x',
+  "git commit '-n' -m x",
+  'env "HUSKY=0" git commit -m x',
+  "git config core.hookspath /dev/null",
+  "git -c core.HooksPath=/dev/null commit -m x",
+  "git -c alias.c='commit --no-verify' c",
+  "git config alias.c commit",
+  "git commit-tree HEAD^{tree} -m x",
+  "git update-ref refs/heads/main HEAD",
+  "printf 'exit 0' > .husky/pre-commit",
+  "rm -rf .husky/_",
+  "sed -i '' s/gitleaks/true/ .husky/pre-commit",
+  "tee .gitleaks.toml < /dev/null",
+  "cp /dev/null .agents/hooks/agent-shell-gate.sh",
+  "git -c core.hooks\\Path=/dev/null commit -m x",
+  "git commit --no-ver\\ify -m x",
+  "HU\\SKY=0 git commit -m x",
+  "git commit -m x --no-$(echo verify)",
+  "/usr/bin/git commit -n -m x",
+  "git --git-dir .git commit -n -m x",
+  "git commit -n; git status",
+  "git commit -m x -n&&git push",
+  "rm -rf .husky",
+  "mv .husky /tmp/h",
+  "sed -e s/a/b/ -i .husky/pre-commit",
+  "python3 -c \"open('.husky/pre-commit','w')\"",
+  "dd of=.husky/pre-commit",
+  "git config core.hooks$X x",
+  "cd .husky && python3 -c \"open('pre-commit','w')\"",
+  "GIT_CONFIG_KEY_0=core.hooksPath GIT_CONFIG_VALUE_0=/x git commit -m x",
+  'bash -c "git commit -n -m x"',
+  "eval git commit -n -m x",
+  "git checkout -- .husky/pre-commit",
+  "echo x >> .claude/settings.local.json",
+  "git merge --no-verify feature",
+  "$(git commit --no-verify -m x)",
+  "echo `git commit -n -m x`",
+  'echo "$(rm -rf .husky)"',
+  "x=$(echo $(git commit -n -m x))",
+  "echo \"$(echo ')'; git commit --no-verify -m x)\"",
+  "$(echo \\); git commit -n -m x)",
+  "$(echo x # )\ngit commit -n -m x)",
+  'echo "$(true&# )\ngit commit -n -m x)"',
+  'echo "$(true|# )\ngit commit -n -m x)"',
+  'echo "$( (true)# )\ngit commit -n -m x)"',
+];
+
+const allowedCommands = [
+  'git commit -m "add login"',
+  "git commit --signoff -m x",
+  "git commit --amend --no-edit",
+  "git status",
+  "pnpm check",
+  "git commit --verbose -m x",
+  "cat .husky/pre-commit",
+  "git diff .husky/pre-commit",
+  'git commit -m "feat(x): y" && git log -n 3',
+  "git commit -m x; ls -n",
+  "git commit -m \"$(printf 'feat(x): y')\"",
+  "echo '$(git commit -n -m x)'",
+  'git commit -m "run with -n"',
+  'git commit -am "fix: -n flag handling"',
+  "git diff .husky/pre-commit > /tmp/x",
+  "ls .husky/ ; cp a b",
+  'git commit -m "chore: rm .husky/pre-commit file"',
+  'gh pr create --title "docs(x): explain core.hooksPath"',
+  'gh pr create --title "ci(x): remove HUSKY=0 usage"',
+  "git push -n",
+  "node scripts/check-agent-gates.ts",
+];
+
+const protectedPaths = [
+  ".agents/rules/code-comments.md",
+  ".agents/rules.json",
+  ".agents/hooks/agent-shell-gate.sh",
+  ".claude/rules/code-comments.md",
+  ".claude/settings.json",
+  ".cursor/rules/code-comments.mdc",
+  ".cursor/hooks.json",
+  ".cursor/hooks/agent-constitution-gate.sh",
+  "scripts/sync-agent-rules.ts",
+  "eslint.config.ts",
+  ".husky/pre-commit",
+  ".lintstagedrc.json",
+  ".gitleaks.toml",
+  ".claude/settings.local.json",
+  "src/../.husky/pre-commit",
+];
+
+const cases: GateCase[] = [
+  ...blockedCommands.flatMap(command => [
+    {
+      gate: shellGate,
+      input: {
+        command,
+      },
+      expectedExit: 2 as const,
+      name: `Cursor shell: ${command}`,
+    },
+    {
+      gate: shellGate,
+      input: {
+        tool_input: {
+          command,
+        },
+      },
+      expectedExit: 2 as const,
+      name: `Claude Bash: ${command}`,
+    },
+  ]),
+  ...allowedCommands.map(command => ({
+    gate: shellGate,
+    input: {
+      command,
+    },
+    expectedExit: 0 as const,
+    name: `shell: ${command}`,
+  })),
+  {
+    gate: suppressionGate,
+    name: "suppression: eslint-disable",
+    expectedExit: 2,
+    input: {
+      tool_input: {
+        file_path: sourceFile,
+        content: "// eslint-disable-next-line\n",
+      },
+    },
+  },
+  ...["// NOSONAR", "# noqa: E501", "# hadolint ignore=DL3008", "# trivy:ignore:AVD-DS-0002"].map(
+    content => ({
+      gate: suppressionGate,
+      input: {
+        tool_input: {
+          file_path: sourceFile,
+          content,
+        },
+      },
+      expectedExit: 2 as const,
+      name: `suppression: ${content}`,
+    }),
+  ),
+  {
+    gate: suppressionGate,
+    name: "suppression: noqa inside a word",
+    expectedExit: 0,
+    input: {
+      tool_input: {
+        file_path: sourceFile,
+        content: "const canoqaValue = 1;\n",
+      },
+    },
+  },
+  {
+    gate: suppressionGate,
+    name: "suppression: exempt directory reached through ..",
+    expectedExit: 2,
+    input: {
+      tool_input: {
+        file_path: ".agents/rules/../../src/example.ts",
+        content: "// eslint-disable-next-line\n",
+      },
+    },
+  },
+  {
+    gate: suppressionGate,
+    name: "suppression: clean edit",
+    expectedExit: 0,
+    input: {
+      tool_input: {
+        file_path: sourceFile,
+        content: "export const value = 1;\n",
+      },
+    },
+  },
+  ...protectedPaths.map(file => ({
+    gate: constitutionGate,
+    input: {
+      tool_input: {
+        file_path: file,
+      },
+    },
+    expectedExit: 2 as const,
+    name: `constitution: ${file}`,
+  })),
+  {
+    gate: constitutionGate,
+    name: "constitution: src file",
+    expectedExit: 0,
+    input: {
+      tool_input: {
+        file_path: sourceFile,
+      },
+    },
+  },
+];
+
+const failures = cases.filter(gateCase => {
+  const result = spawnSync(gateCase.gate, {
+    env: {
+      ...process.env,
+      CLAUDE_PROJECT_DIR: process.cwd(),
+      CURSOR_PROJECT_DIR: process.cwd(),
+    },
+    input: JSON.stringify(gateCase.input),
+  });
+
+  return result.status !== gateCase.expectedExit;
+});
+
+if (failures.length > 0) {
+  const failureLines = failures.map(
+    gateCase => `- ${gateCase.name} (expected exit ${gateCase.expectedExit})`,
+  );
+
+  process.stderr.write(`Agent gate checks failed:\n${failureLines.join("\n")}\n`);
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`Checked ${cases.length} agent gate cases.\n`);
+}

package/templates/base/scripts/sync-agent-rules.ts

@@ -0,0 +1,121 @@
+import {existsSync, readdirSync, readFileSync, writeFileSync} from "node:fs";
+import path from "node:path";
+
+type RuleConfig = {
+  description: string;
+  globs?: string[];
+};
+
+const sourceDirectory = ".agents/rules";
+const configPath = ".agents/rules.json";
+
+const claudeExtras: Record<string, string> = {
+  "agents-guide.md": "@../../AGENTS.md\n",
+};
+
+/**
+ * List the names of files with an extension in a directory.
+ * @param directory Directory to read.
+ * @param extension File extension, including the dot.
+ * @returns File names without the extension.
+ */
+function listNames(directory: string, extension: string): string[] {
+  return readdirSync(directory)
+    .filter(file => file.endsWith(extension))
+    .map(file => file.slice(0, -extension.length));
+}
+
+/**
+ * Render the Claude Code rule: an import for an always-on rule, the full body behind `paths` for a scoped rule.
+ * @param name Rule name.
+ * @param rule Rule configuration.
+ * @param body Shared rule body.
+ * @returns The `.claude/rules` file content.
+ */
+function renderClaudeRule(name: string, rule: RuleConfig, body: string): string {
+  if (rule.globs === undefined) {
+    return `@../../${sourceDirectory}/${name}.md\n`;
+  }
+
+  const paths = rule.globs.map(glob => `  - "${glob}"`).join("\n");
+
+  return `---\npaths:\n${paths}\n---\n\n${body}`;
+}
+
+/**
+ * Render the Cursor rule with the full body, because Cursor does not inline referenced files.
+ * @param rule Rule configuration.
+ * @param body Shared rule body.
+ * @returns The `.cursor/rules` file content.
+ */
+function renderCursorRule(rule: RuleConfig, body: string): string {
+  const scope =
+    rule.globs === undefined
+      ? "alwaysApply: true"
+      : `globs: "${rule.globs.join(",")}"\nalwaysApply: false`;
+
+  return `---\ndescription: "${rule.description}"\n${scope}\n---\n\n${body}`;
+}
+
+const config = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, RuleConfig>;
+const configNames = Object.keys(config);
+const sourceNames = listNames(sourceDirectory, ".md");
+const missingConfig = sourceNames.filter(name => !configNames.includes(name));
+const missingSource = configNames.filter(name => !sourceNames.includes(name));
+
+if (missingConfig.length > 0 || missingSource.length > 0) {
+  throw new Error(
+    `${configPath} and ${sourceDirectory} must list the same rules. Missing from ${configPath}: ${missingConfig.join(", ") || "none"}. Missing from ${sourceDirectory}: ${missingSource.join(", ") || "none"}.`,
+  );
+}
+
+const claudeDirectory = ".claude/rules";
+const cursorDirectory = ".cursor/rules";
+const expected = new Map<string, string>();
+
+for (const name of configNames) {
+  const rule = config[name];
+  const body = readFileSync(path.join(sourceDirectory, `${name}.md`), "utf8");
+
+  expected.set(path.join(claudeDirectory, `${name}.md`), renderClaudeRule(name, rule, body));
+  expected.set(path.join(cursorDirectory, `${name}.mdc`), renderCursorRule(rule, body));
+}
+
+for (const [file, content] of Object.entries(claudeExtras)) {
+  expected.set(path.join(claudeDirectory, file), content);
+}
+
+const orphans = [
+  ...listNames(claudeDirectory, ".md").map(name => path.join(claudeDirectory, `${name}.md`)),
+  ...listNames(cursorDirectory, ".mdc").map(name => path.join(cursorDirectory, `${name}.mdc`)),
+].filter(file => !expected.has(file));
+
+if (orphans.length > 0) {
+  throw new Error(
+    `Generated rule files without a source: ${orphans.join(", ")}. Delete them or add the rule to ${configPath}.`,
+  );
+}
+
+const isCheckOnly = process.argv.includes("--check");
+
+const staleFiles = [...expected].filter(
+  ([file, content]) => !existsSync(file) || readFileSync(file, "utf8") !== content,
+);
+
+if (!isCheckOnly) {
+  for (const [file, content] of staleFiles) {
+    writeFileSync(file, content);
+  }
+}
+
+if (isCheckOnly && staleFiles.length > 0) {
+  process.stderr.write(
+    `Agent rules are out of date: ${staleFiles.map(([file]) => file).join(", ")}. Run \`pnpm rules:sync\`.\n`,
+  );
+
+  process.exitCode = 1;
+} else {
+  process.stdout.write(
+    `${isCheckOnly ? "Checked" : "Synced"} ${expected.size} agent rule files; ${staleFiles.length} ${isCheckOnly ? "stale" : "updated"}.\n`,
+  );
+}

package/templates/nestjs/.agents/rules/typescript-first.md

@@ -0,0 +1,7 @@
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

package/templates/nestjs/.agents/rules.json

@@ -0,0 +1,41 @@
+{
+  "automation-owned-checks": {
+    "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
+  },
+  "code-comments": {
+    "description": "Required comments: comment only where a tool or rule needs it, or for a reason the code cannot show"
+  },
+  "current-state-authority": {
+    "description": "Current state: implement from user requirements and the working tree"
+  },
+  "demand-driven-configuration": {
+    "description": "Demand-driven configuration: add a setting only for an active requirement"
+  },
+  "dependency-security": {
+    "description": "Dependencies: add a package only when code or a contract uses it",
+    "globs": ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]
+  },
+  "deterministic-testing": {
+    "description": "Test admission: add a case only when it catches a defect current tests miss",
+    "globs": ["**/*.test.ts"]
+  },
+  "diagnostics-and-error-handling": {
+    "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
+  },
+  "git-workflow": {
+    "description": "Git workflow: trunk-based branches, commits, and pull requests"
+  },
+  "no-suppression": {
+    "description": "Findings: fix scanner and linter reports without inline suppressions"
+  },
+  "script-driven-changes": {
+    "description": "Scripts: apply a repeated edit across many files with a script"
+  },
+  "single-author-style": {
+    "description": "Sibling style: match layout, naming, and composition in the same project"
+  },
+  "typescript-first": {
+    "description": "TypeScript-first: write source, tests, and scripts as .ts",
+    "globs": ["**/*.ts", "**/*.js"]
+  }
+}

package/templates/nestjs/.claude/rules/deterministic-testing.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "**/*.test.ts"
+---
+
+# Test Admission
+
+Keep tests as small, deterministic protections for observable contracts.
+
+Name the contract and the distinct defect a proposed test can detect before writing it. Admit a test for externally observable behavior, a public contract, a demonstrated regression, a non-trivial invariant, a meaningful failure mode, or an explicit repository verification requirement.
+
+Choose the narrowest existing layer that owns that contract. Give each test one defect to detect. Add a case only when it catches a defect remaining cases miss. Treat coverage percentage as a measurement.
+
+Search existing coverage first. Extend the file that already owns the contract. Create a file only when the contract has no owner or needs a different harness. Follow the nearest directory and naming pattern. Keep setup local until multiple tests share live runtime logic, then extract one helper.
+
+Use the framework's standard assertions. Use an inline snippet unless filesystem paths, module resolution, or compiler services are the contract. Keep fixtures declarative and read-only.
+
+When the user asks to run tests, run the narrowest owning file or filter.
+
+_Completion criterion_: Every added or modified case maps to an admitted contract and a defect current cases would miss. Tests stay unchanged when no proposed case survives admission.

package/templates/nestjs/.claude/rules/typescript-first.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.js"
+---
+
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

package/templates/nestjs/.cursor/rules/deterministic-testing.mdc

@@ -0,0 +1,21 @@
+---
+description: "Test admission: add a case only when it catches a defect current tests miss"
+globs: "**/*.test.ts"
+alwaysApply: false
+---
+
+# Test Admission
+
+Keep tests as small, deterministic protections for observable contracts.
+
+Name the contract and the distinct defect a proposed test can detect before writing it. Admit a test for externally observable behavior, a public contract, a demonstrated regression, a non-trivial invariant, a meaningful failure mode, or an explicit repository verification requirement.
+
+Choose the narrowest existing layer that owns that contract. Give each test one defect to detect. Add a case only when it catches a defect remaining cases miss. Treat coverage percentage as a measurement.
+
+Search existing coverage first. Extend the file that already owns the contract. Create a file only when the contract has no owner or needs a different harness. Follow the nearest directory and naming pattern. Keep setup local until multiple tests share live runtime logic, then extract one helper.
+
+Use the framework's standard assertions. Use an inline snippet unless filesystem paths, module resolution, or compiler services are the contract. Keep fixtures declarative and read-only.
+
+When the user asks to run tests, run the narrowest owning file or filter.
+
+_Completion criterion_: Every added or modified case maps to an admitted contract and a defect current cases would miss. Tests stay unchanged when no proposed case survives admission.

package/templates/nestjs/.cursor/rules/typescript-first.mdc

@@ -0,0 +1,13 @@
+---
+description: "TypeScript-first: write source, tests, and scripts as .ts"
+globs: "**/*.ts,**/*.js"
+alwaysApply: false
+---
+
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

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

@@ -0,0 +1,28 @@
+{
+  "extends": "dependency-cruiser/configs/recommended-strict",
+  "forbidden": [
+    {
+      "name": "no-orphans",
+      "to": {},
+      "from": {
+        "orphan": true,
+        "pathNot": [
+          "(^|/)tsconfig\\.json$",
+          "(^|/)eslint\\.config\\.ts$",
+          "(^|/)vitest([.]e2e)?[.]config[.]ts$",
+          "[.]test[.]ts$",
+          "^src/main[.]ts$"
+        ]
+      }
+    }
+  ],
+  "options": {
+    "skipAnalysisNotInRules": true,
+    "tsPreCompilationDeps": true,
+    "enhancedResolveOptions": {
+      "conditionNames": ["import", "require", "node", "default", "types"],
+      "exportsFields": ["exports"]
+    },
+    "exclude": "(^|/)(?:dist|coverage|node_modules)/"
+  }
+}

package/templates/nestjs/.dockerignore

@@ -0,0 +1,8 @@
+*
+!package.json
+!pnpm-lock.yaml
+!pnpm-workspace.yaml
+!tsconfig.json
+!tsconfig.build.json
+!src/
+src/**/*.test.ts

package/templates/nestjs/.env.example

@@ -0,0 +1 @@
+PORT=3000

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

@@ -0,0 +1,66 @@
+name: Bug report
+description: Report crashes, incorrect behavior, or setup problems.
+labels: ["bug", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Reproduce the issue with the supported Node.js version.
+        Remove credentials, secrets, personal or customer data, and proprietary source code before submitting.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you submit
+      description: Confirm these items before submitting the report.
+      options:
+        - label: I searched existing issues and didn't find a matching report.
+          required: true
+        - label: I can reproduce this issue on the latest commit of the default branch.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Commit
+      placeholder: 769e0ef
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: List Node.js, operating system, package manager, and the request that triggers the issue.
+      placeholder: |
+        Node.js: 24.22.1
+        OS: Ubuntu 24.04 / macOS
+        Package manager: pnpm 12.6.0
+        Request: curl -i http://localhost:3000/
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Link to a minimal public reproduction or provide sanitized code and configuration that reproduce the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Describe the behavior you expected.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Describe what happened, including the response status, response body, errors, and server logs.
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Sensitive information
+      options:
+        - label: I removed credentials, secrets, personal or customer data, and proprietary code from this report.
+          required: true

package/templates/nestjs/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Suggest a specific change to next-friday-template-nestjs.
+labels: ["enhancement", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for changes that are ready to evaluate.
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Affected area
+      description: Select the area this request affects.
+      options:
+        - Modules and endpoints
+        - Configuration and environment
+        - Testing
+        - Tooling / CI
+        - Documentation
+        - Repository governance
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the problem or use case.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Describe the smallest change that solves the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List existing options you considered.
+    validations:
+      required: false
+  - type: checkboxes
+    id: breaking
+    attributes:
+      label: Breaking change
+      description: Indicate whether this request changes behavior for existing users.
+      options:
+        - label: This request changes an existing endpoint or public contract.

package/templates/nestjs/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- Title: `<type>(<scope>): <subject>` with a lowercase scope and a subject of 50 characters or fewer. Repository workflows validate it. The squash merge puts the title on `main`. Delete a section that has nothing to say, except Scope. -->
+
+## Why
+
+<!-- The problem and the approach in 1-3 short sentences. No SHAs or rebase history. Link a related issue with `Closes #123`. -->
+
+## What changed
+
+<!-- 1-3 short bullets. Name a symbol or path only when it carries the change, and both sides of a rename. Name every added, changed, or removed endpoint, request or response field, and environment variable. Document new variables in `.env.example`. -->
+
+## Scope
+
+<!-- 1-3 short items: what this covers and what it deliberately leaves out. -->
+
+## Tradeoffs
+
+<!-- Only rejected alternatives a reviewer would ask about. -->
+
+## Blast Radius
+
+<!-- 1-2 sentences on who or what this touches and why that is safe or risky. If main is red, state the cost of leaving it red. -->
+
+## Verification
+
+<!-- 1-3 bullets, each a check you ran and its outcome. For a perf change, one number as before -> after. After this section, attach videos or screenshots that prove a claim. -->