@next-friday/create-app 9.4.1 → 9.5.1

package/package.json

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

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

@@ -1,12 +1,20 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
+# shellcheck source=.agents/hooks/record-gate-decision.sh
+if ! source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/record-gate-decision.sh"; then
+  printf '%s\n' '{"permission":"deny","user_message":"agent-mcp-gate: .agents/hooks/record-gate-decision.sh could not be loaded, so the gate cannot record its decision. Stop and report this error to the user; agents may not edit the gate."}'
+  exit 2
+fi
+
 allow() {
+  record_gate_decision agent-mcp-gate allow "" "${input:-}" "${lifted_approval:-}"
   printf '%s\n' '{"permission":"allow"}'
   exit 0
 }
 
 block() {
+  record_gate_decision agent-mcp-gate block "${2:-$1}" "${input:-}"
   jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
   printf 'agent-mcp-gate: %s\n' "$1" >&2
   exit 2

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

@@ -1,12 +1,20 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
+# shellcheck source=.agents/hooks/record-gate-decision.sh
+if ! source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/record-gate-decision.sh"; then
+  printf '%s\n' '{"permission":"deny","user_message":"agent-production-gate: .agents/hooks/record-gate-decision.sh could not be loaded, so the gate cannot record its decision. Stop and report this error to the user; agents may not edit the gate."}'
+  exit 2
+fi
+
 allow() {
+  record_gate_decision agent-production-gate allow "" "${input:-}" "${lifted_approval:-}"
   printf '%s\n' '{"permission":"allow"}'
   exit 0
 }
 
 block() {
+  record_gate_decision agent-production-gate block "${2:-$1}" "${input:-}"
   jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
   printf 'agent-production-gate: %s\n' "$1" >&2
   exit 2
@@ -14,15 +22,26 @@ block() {
 
 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')
+input=$(cat)
+command=$(jq -r '.command // .tool_input.command // empty' <<< "$input")
 [[ -n $command ]] || allow
-approval=$(tr '[:upper:]' '[:lower:]' <<< "${RELEASE_APPROVAL:-}")
-case $approval in
+project=${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-$PWD}}
+approval_form_file=.agents/release-approval-form
+approval=${RELEASE_APPROVAL:-}
+unmatched_approval=
+case $(tr '[:upper:]' '[:lower:]' <<< "$approval") in
   "" | 0 | false | no) ;;
-  *) allow ;;
+  *)
+    approval_form=$(head -n 1 "$project/$approval_form_file" 2> /dev/null) || approval_form=
+    if [[ -n $approval_form && $approval =~ $approval_form ]]; then
+      lifted_approval=$approval
+      allow
+    fi
+    unmatched_approval=" RELEASE_APPROVAL is set and does not match the form in $approval_form_file, so the gate stays in force."
+    ;;
 esac
 
-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>."
+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>.$unmatched_approval"
 
 # 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

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

@@ -1,12 +1,20 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
+# shellcheck source=.agents/hooks/record-gate-decision.sh
+if ! source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/record-gate-decision.sh"; then
+  printf '%s\n' '{"permission":"deny","user_message":"agent-shell-gate: .agents/hooks/record-gate-decision.sh could not be loaded, so the gate cannot record its decision. Stop and report this error to the user; agents may not edit the gate."}'
+  exit 2
+fi
+
 allow() {
+  record_gate_decision agent-shell-gate allow "" "${input:-}" "${lifted_approval:-}"
   printf '%s\n' '{"permission":"allow"}'
   exit 0
 }
 
 block() {
+  record_gate_decision agent-shell-gate block "${2:-$1}" "${input:-}"
   jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
   printf 'agent-shell-gate: %s\n' "$1" >&2
   exit 2
@@ -147,7 +155,7 @@ lex() {
 }
 
 writes_protected() {
-  block "Changing $1 from the shell is blocked. $policy"
+  block "Changing $1 from the shell is blocked. $policy" "Changing a protected path from the shell is blocked. $policy"
 }
 
 check_git() {

package/templates/base/.agents/hooks/agent-test-edit-gate.sh

@@ -1,12 +1,20 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
+# shellcheck source=.agents/hooks/record-gate-decision.sh
+if ! source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/record-gate-decision.sh"; then
+  printf '%s\n' '{"permission":"deny","user_message":"agent-test-edit-gate: .agents/hooks/record-gate-decision.sh could not be loaded, so the gate cannot record its decision. Stop and report this error to the user; agents may not edit the gate."}'
+  exit 2
+fi
+
 allow() {
+  record_gate_decision agent-test-edit-gate allow "" "${input:-}" "${lifted_approval:-}"
   printf '%s\n' '{"permission":"allow"}'
   exit 0
 }
 
 block() {
+  record_gate_decision agent-test-edit-gate block "${2:-$1}" "${input:-}"
   jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
   printf 'agent-test-edit-gate: %s\n' "$1" >&2
   exit 2
@@ -20,7 +28,7 @@ project=${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-$PWD}}
 path=$(jq -r '.tool_input.file_path // .tool_input.path // .tool_input.notebook_path // .file_path // empty' <<< "$input")
 [[ -n $path && $path =~ $test_path_pattern ]] || allow
 if [[ -e "$project/.git/bug-fix-in-progress" ]]; then
-  block "A bug fix is in progress (.git/bug-fix-in-progress), so $path cannot change. Fix the code, not the test."
+  block "A bug fix is in progress (.git/bug-fix-in-progress), so $path cannot change. Fix the code, not the test." "A bug fix is in progress (.git/bug-fix-in-progress), so a test file cannot change."
 fi
 branch=$(git -C "$project" symbolic-ref --quiet --short HEAD 2> /dev/null) || branch=
 [[ $branch == fix/* ]] || allow
@@ -29,6 +37,6 @@ git -C "$project" rev-parse --verify --quiet "$default_branch" > /dev/null 2>&1
 merge_base=$(git -C "$project" merge-base HEAD "$default_branch" 2> /dev/null) || allow
 committed_files=$(git -C "$project" log --format= --name-only "$merge_base..HEAD" 2> /dev/null) || allow
 if grep -Eq "$test_path_pattern" <<< "$committed_files"; then
-  block "A bug fix is in progress on branch $branch and the test that reproduces it is committed, so $path cannot change. Fix the code, not the test."
+  block "A bug fix is in progress on branch $branch and the test that reproduces it is committed, so $path cannot change. Fix the code, not the test." "A bug fix is in progress on a fix branch whose test is committed, so a test file cannot change."
 fi
 allow

package/templates/base/.agents/hooks/record-gate-decision.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Sourced by each gate hook. A record never changes the hook's answer: a failed write is reported
+# on standard error and the function returns 0. The record holds no command text, path, file
+# content, or environment value, because any of them can hold a secret: a hook passes a reason
+# with no text from its input. A lifted production gate adds the approval value and the Git user
+# name, which the release record needs.
+record_gate_decision() {
+  local hook=$1 decision=$2 reason=$3 input=$4 approval=${5:-} project log session
+  project=${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-$PWD}}
+  log=${AGENT_GATE_LOG:-$project/.agents/logs/gate-decisions.jsonl}
+  session=$(jq -r '.session_id // .conversation_id // empty' <<< "$input" 2> /dev/null) || session=
+  {
+    mkdir -p "${log%/*}" \
+      && jq -cn \
+        --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+        --arg hook "$hook" \
+        --arg decision "$decision" \
+        --arg reason "$reason" \
+        --arg session "$session" \
+        --arg approval "$approval" \
+        --arg user "$([[ -n $approval ]] && git -C "$project" config user.name 2> /dev/null)" \
+        '{time: $time, hook: $hook, decision: $decision}
+          + (if $reason == "" then {} else {reason: $reason} end)
+          + (if $session == "" then {} else {session: $session} end)
+          + (if $approval == "" then {} else {approval: $approval, user: $user} end)' >> "$log"
+  } 2> /dev/null || printf '%s: could not write the decision record to %s\n' "$hook" "$log" >&2
+  return 0
+}

package/templates/base/.agents/release-approval-form

@@ -0,0 +1 @@
+^[A-Z]+-[0-9]+$

package/templates/base/.cursor/hooks/agent-constitution-gate.sh

@@ -3,12 +3,20 @@ set -uo pipefail
 
 protected='^(\.agents/rules/|\.agents/rules\.json$|\.agents/hooks/|\.claude/rules/|\.claude/settings(\.local)?\.json$|\.cursor/rules/|\.cursor/hooks/|\.cursor/hooks\.json$|scripts/sync-agent-rules\.ts$|scripts/check-agent-gates\.ts$|\.commitlintrc\.json$|\.prettierrc\.json$|prettier\.config\.ts$|eslint\.config\.ts$|\.husky/|\.lintstagedrc\.json$|\.gitleaks\.toml$|\.git/hooks/|\.git/config(\.worktree)?$)'
 
+# shellcheck source=.agents/hooks/record-gate-decision.sh
+if ! source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../.agents/hooks/record-gate-decision.sh"; then
+  printf '%s\n' '{"permission":"deny","user_message":"agent-constitution-gate: .agents/hooks/record-gate-decision.sh could not be loaded, so the gate cannot record its decision. Stop and report this error to the user; agents may not edit the gate."}'
+  exit 2
+fi
+
 allow() {
+  record_gate_decision agent-constitution-gate allow "" "${input:-}" "${lifted_approval:-}"
   printf '%s\n' '{"permission":"allow"}'
   exit 0
 }
 
 block() {
+  record_gate_decision agent-constitution-gate block "${2:-$1}" "${input:-}"
   jq -n --arg message "$1" '{permission:"deny",user_message:$message,agent_message:$message}'
   printf 'agent-constitution-gate: %s\n' "$1" >&2
   exit 2
@@ -26,7 +34,7 @@ project=${CURSOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-${project:-$PWD}}}
 [[ $path == "$project"/* ]] || allow
 relative=${path#"$project"/}
 if [[ $relative =~ (^|/)\.\.?(/|$) ]]; then
-  block "The edit to $relative uses . or .. in its path. Use the normalized path."
+  block "The edit to $relative uses . or .. in its path. Use the normalized path." "The edit uses . or .. in its path."
 fi
 [[ $relative =~ $protected ]] || allow
-block "The edit to $relative is blocked. That path is company policy; stop and ask the user."
+block "The edit to $relative is blocked. That path is company policy; stop and ask the user." "The edit to a company policy path is blocked."

package/templates/base/SETUP.md

@@ -92,7 +92,7 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 - **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):** the plugin ships a default for each area, `plugins/sdlc/claude-code/skills/<area>-policy/SKILL.md` (security: OWASP ASVS 5.0.0 Level 1; UX: WCAG 2.2 Level AA; compliance: the OECD privacy principles; brand: one declared source for every brand value). Review it. To replace a default, add the organization's own rules in `.agents/skills/<area>-policy/SKILL.md` in the project: that file wins over the plugin's default, and the `CODEOWNERS` line of step 2 for that area makes the policy owner its code owner. Do not edit the plugin's copy. Then run `pnpm rules:sync`, which renders the project's own policy skill for Claude Code and Cursor. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time.
-- **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`. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case.
+- **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`. The value lifts the gate only when it matches the extended regular expression on the first line of `.agents/release-approval-form`, shipped as `^[A-Z]+-[0-9]+$`; set that line to the form of your organization's approval records. Each gate hook appends its decisions to `.agents/logs/gate-decisions.jsonl`, which git ignores: the time, the hook, the decision, the session, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name. A record holds no command text and no path.
 - **Review (tech lead):** `.agents/review.md` names this stack's generated files to skip; add a path when the project gains a generated file, 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/scripts/check-agent-gates.ts

@@ -1,13 +1,16 @@
 import {execFileSync, spawnSync} from "node:child_process";
-import {mkdtempSync, rmSync, writeFileSync} from "node:fs";
+import {existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync} from "node:fs";
 import path from "node:path";
 import {tmpdir} from "node:os";
 
 type GateCase = {
+  expectedApproval?: string;
   expectedExit: 0 | 2;
   expectedPermission?: "allow";
+  expectedSession?: string;
   gate: string;
   input: Record<string, unknown>;
+  isRecordUnwritable?: boolean;
   name: string;
   projectDirectory?: string;
   releaseApproval?: string;
@@ -31,6 +34,7 @@ const mcpGate = ".agents/hooks/agent-mcp-gate.sh";
 const productionGate = ".agents/hooks/agent-production-gate.sh";
 const testEditGate = ".agents/hooks/agent-test-edit-gate.sh";
 const sourceFile = "src/example.ts";
+const statusCommand = "git status";
 
 const blockedCommands = [
   "printf 'exit 0' > .husky/pre-commit",
@@ -109,7 +113,7 @@ const blockedCommands = [
 
 const allowedCommands = [
   'git commit -m "add login"',
-  "git status",
+  statusCommand,
   "pnpm check",
   "cat .husky/pre-commit",
   "git diff .husky/pre-commit",
@@ -205,8 +209,22 @@ const productionCommands = [
   "cd a\\\\\ngit push origin v1.0.0",
 ];
 
-const approvalLiftsGate = ["CHG-123", "1", "CHG-1", "off", "00", " "];
-const approvalKeepsGate = ["", "0", "false", "no", "FALSE", "No", "nO"];
+const approvalLiftsGate = ["CHG-123", "CHG-1"];
+
+const approvalKeepsGate = [
+  "",
+  "0",
+  "false",
+  "no",
+  "FALSE",
+  "No",
+  "nO",
+  "1",
+  "off",
+  "00",
+  " ",
+  "chg-123",
+];
 
 const nonProductionCommands = [
   "gh workflow run deploy.yml -f environment=uat -f commit_sha=abc",
@@ -440,6 +458,7 @@ const cases: GateCase[] = [
   ...approvalLiftsGate.map(releaseApproval => ({
     gate: productionGate,
     releaseApproval,
+    expectedApproval: releaseApproval,
     input: {
       tool_input: {
         command: railwayProductionCommand,
@@ -554,12 +573,166 @@ const cases: GateCase[] = [
     expectedExit: expectedExit as 0 | 2,
     name: `test edit: ${name}`,
   })),
+  {
+    gate: shellGate,
+    expectedPermission: "allow",
+    expectedSession: "claude-session",
+    name: "record: the session of a Claude Code hook input",
+    expectedExit: 0,
+    input: {
+      command: statusCommand,
+      session_id: "claude-session",
+    },
+  },
+  {
+    gate: productionGate,
+    expectedSession: "cursor-conversation",
+    name: "record: the conversation of a Cursor hook input",
+    expectedExit: 2,
+    input: {
+      command: railwayProductionCommand,
+      conversation_id: "cursor-conversation",
+    },
+  },
+  {
+    gate: shellGate,
+    name: "record: a blocked command that holds a secret",
+    expectedExit: 2,
+    input: {
+      command: "rm sk_live_SECRET123=.agents/hooks/agent-shell-gate.sh",
+    },
+  },
+  {
+    gate: constitutionGate,
+    name: "record: a blocked path that holds a secret",
+    expectedExit: 2,
+    input: {
+      file_path: ".agents/rules/sk_live_SECRET123.md",
+    },
+  },
+  {
+    gate: productionGate,
+    projectDirectory: outsideRepository,
+    name: "record: an approval in the form when the project has no form file",
+    releaseApproval: "CHG-123",
+    expectedExit: 2,
+    input: {
+      command: railwayProductionCommand,
+    },
+  },
+  {
+    gate: shellGate,
+    expectedPermission: "allow",
+    name: "record: an allow when the record cannot be written",
+    expectedExit: 0,
+    isRecordUnwritable: true,
+    input: {
+      command: statusCommand,
+    },
+  },
+  {
+    gate: productionGate,
+    name: "record: a block when the record cannot be written",
+    expectedExit: 2,
+    isRecordUnwritable: true,
+    input: {
+      command: railwayProductionCommand,
+    },
+  },
 ];
 
-const failures = cases.filter(gateCase => {
+const recordDirectory = mkdtempSync(path.join(tmpdir(), "agent-gates-records-"));
+const recordKeys = new Set(["approval", "decision", "hook", "reason", "session", "time", "user"]);
+
+const gitUsername = spawnSync("git", ["config", "user.name"], {
+  encoding: "utf8",
+}).stdout.trim();
+
+const unwritableRecord = path.join(recordDirectory, "a-file");
+
+writeFileSync(unwritableRecord, "");
+
+/**
+ * Read the lines a gate appended to its record.
+ * @param recordPath The file the gate was told to append to.
+ * @returns The lines, or none when the gate wrote no file.
+ */
+function readRecordLines(recordPath: string): string[] {
+  return existsSync(recordPath) ? readFileSync(recordPath, "utf8").trim().split("\n") : [];
+}
+
+/**
+ * List the words of a hook input that look like a path, an assignment, or a file name.
+ * @param input The hook input.
+ * @returns Each such word of six characters or more.
+ */
+function listInputWords(input: Record<string, unknown>): string[] {
+  return JSON.stringify(input)
+    .split(/[\s"'\\{}:,]+/u)
+    .filter(word => word.length >= 6 && /[./=]/u.test(word));
+}
+
+/**
+ * Tell whether a gate wrote the record its decision calls for, and nothing a record must not hold.
+ * @param gateCase The case that ran.
+ * @param recordPath The file the gate was told to append to.
+ * @returns True when the record is missing, malformed, or wrong.
+ */
+function isRecordWrong(gateCase: GateCase, recordPath: string): boolean {
+  type DecisionRecord = {
+    approval?: string;
+    decision?: string;
+    hook?: string;
+    reason?: string;
+    session?: string;
+    time?: string;
+    user?: string;
+  };
+
+  const lines = readRecordLines(recordPath);
+  const lastLine = lines.at(-1) ?? "{}";
+  const record = JSON.parse(lastLine) as DecisionRecord;
+  const isBlock = gateCase.expectedExit === 2;
+  const isLifted = gateCase.expectedApproval !== undefined;
+  const secondsFromNow = Math.abs(Date.now() - Date.parse(record.time ?? "")) / 1000;
+
+  const found = [
+    record.decision,
+    record.hook,
+    record.session,
+    record.approval,
+    record.user,
+    record.reason !== undefined,
+    (record.time ?? "").endsWith("Z") && secondsFromNow < 600,
+    Object.keys(record).every(key => recordKeys.has(key)),
+  ];
+
+  const expected = [
+    isBlock ? "block" : "allow",
+    path.basename(gateCase.gate, ".sh"),
+    gateCase.expectedSession,
+    gateCase.expectedApproval,
+    isLifted ? gitUsername : undefined,
+    isBlock,
+    true,
+    true,
+  ];
+
+  const isHoldingInput = listInputWords(gateCase.input).some(word => lastLine.includes(word));
+
+  return lines.length !== 1 || JSON.stringify(found) !== JSON.stringify(expected) || isHoldingInput;
+}
+
+const failures = cases.filter((gateCase, index) => {
+  const recordPath =
+    gateCase.isRecordUnwritable === true
+      ? path.join(unwritableRecord, "gate-decisions.jsonl")
+      : path.join(recordDirectory, `${index}.jsonl`);
+
   const result = spawnSync(gateCase.gate, {
     env: {
       ...childEnvironment,
+      AGENT_GATE_LOG: recordPath,
       CLAUDE_PROJECT_DIR: gateCase.projectDirectory ?? process.cwd(),
       CURSOR_PROJECT_DIR: gateCase.projectDirectory ?? process.cwd(),
       RELEASE_APPROVAL: gateCase.releaseApproval,
@@ -572,10 +745,17 @@ const failures = cases.filter(gateCase => {
     (JSON.parse(result.stdout.toString()) as {permission?: string}).permission !==
       gateCase.expectedPermission;
 
-  return result.status !== gateCase.expectedExit || isPermissionWrong;
+  const isRecordChecked = gateCase.isRecordUnwritable !== true;
+
+  return (
+    result.status !== gateCase.expectedExit ||
+    isPermissionWrong ||
+    (isRecordChecked && isRecordWrong(gateCase, recordPath))
+  );
 });
 
 for (const directory of [
+  recordDirectory,
   fixBranchWithTest,
   fixBranchWithoutTest,
   featureBranchWithTest,