@next-friday/create-app 9.5.0 → 9.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-friday/create-app",
-  "version": "9.5.0",
+  "version": "9.6.0",
   "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/.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

@@ -43,6 +43,8 @@ In `.github/CODEOWNERS`, add these lines in this order. GitHub uses the last mat
 
 Replace every owner above with a GitHub user or team that has write access to the repository. Also replace the owner placeholder in `.github/zizmor.yml`.
 
+Code owners need: write access to the repository for each owner; for a team, a visible team that itself has write access; and, in a private repository, GitHub Pro, Team, or Enterprise ([code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)). Until the ruleset of step 3 requires their review, a code owner is asked for a review and a pull request merges without it.
+
 Replace `security@example.com` in `SECURITY.md` with the contact the security policy owner names, such as the security email of the company or of the client.
 
 **Check:** on GitHub, open `.github/CODEOWNERS`; GitHub shows no errors in the file. `grep example.com SECURITY.md` prints nothing.
@@ -73,7 +75,7 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
 - **Code Review:** in [**Admin settings → Claude Code**](https://claude.ai/admin-settings/claude-code#code-review), turn on **Allow code review**, install the Claude GitHub App, and add this repository ([set up Code Review](https://code.claude.com/docs/en/code-review-setup)). It needs a Team or Enterprise plan ([availability](https://code.claude.com/docs/en/code-review#availability)). Keep **Review runs** at **After every push**, the default, so every push to a pull request gets a review. Reviews run on Anthropic's infrastructure, so the repository has no review workflow. Anyone with write access can also comment `@claude review` on a pull request to start a review ([comment commands](https://code.claude.com/docs/en/code-review-pull-requests#comment-commands)).
 - **Managed settings:** deploy the non-negotiable settings and hooks as [managed settings](https://code.claude.com/docs/en/settings), tailored from the example in `.claude/managed-settings.example.json`. Engineers cannot override them. When `strictKnownMarketplaces` is set, as in the example, add the marketplace `next-friday-plugins` of this project to it, or Claude Code does not register the project's plugin.
-- **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage).
+- **Monitoring:** turn on the [OpenTelemetry export](https://code.claude.com/docs/en/monitoring-usage). It needs an OpenTelemetry collector or backend that the organization runs, and its endpoint. Set `CLAUDE_CODE_ENABLE_TELEMETRY`, the exporters, and `OTEL_EXPORTER_OTLP_ENDPOINT` in managed settings, or each engineer sets them in a shell or in `~/.claude/settings.json`: Claude Code ignores these variables in the repository's `.claude/settings.json`, so the project cannot turn the export on.
 
 **Check:** the test pull request gets a **Claude Code Review** check run within a few minutes.
 
@@ -92,7 +94,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`. 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, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name.
+- **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/plugins/sdlc/claude-code/hooks/check-reply-shape.sh

@@ -3,8 +3,44 @@ command -v jq > /dev/null || exit 0
 mode=${1:-}
 input=$(cat)
 state_directory=${TMPDIR:-/tmp}/sdlc-reply-shape
-conversation=$(printf '%s' "$input" | jq -r '.conversation_id // ""' | tr -cd 'A-Za-z0-9_-')
+conversation=$(printf '%s' "$input" | jq -r '.conversation_id // .session_id // ""')
+conversation=${conversation:+$(printf '%s' "$conversation" | cksum | tr ' ' '-')}
+project=$(printf '%s' "$input" | jq -r '.cwd // .workspace_roots[0] // ""')
+snapshot_file=$state_directory/$conversation.files
+
+# A copy of the index and a scratch object store keep the project's own Git data unwritten.
+snapshot() {
+  [ -n "$project" ] && [ -n "$conversation" ] || return 1
+  repository=$(git -C "$project" rev-parse --show-toplevel 2> /dev/null) || return 1
+  index=$(git -C "$repository" rev-parse --git-path index) || return 1
+  objects=$(git -C "$repository" rev-parse --git-path objects) || return 1
+  case $index in /*) ;; *) index=$repository/$index ;; esac
+  case $objects in /*) ;; *) objects=$repository/$objects ;; esac
+  scratch=$state_directory/$conversation.git
+  rm -rf "$scratch"
+  mkdir -p "$scratch/objects" || return 1
+  cp "$index" "$scratch/index" 2> /dev/null
+  content=$(
+    export GIT_INDEX_FILE="$scratch/index" GIT_OBJECT_DIRECTORY="$scratch/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$objects"
+    git -C "$repository" add -A -- ':(top)' ':(top,exclude)intent' 2> /dev/null
+    git -C "$repository" ls-files -s -- ':(top)' ':(top,exclude)intent' | cksum
+  )
+  rm -rf "$scratch"
+  printf '%s|%s' "$repository" "$content"
+}
+
+changed_since_snapshot() {
+  current=$(snapshot) || return 1
+  previous=$(cat "$snapshot_file" 2> /dev/null)
+  printf '%s' "$current" > "$snapshot_file"
+  [ "${previous%|*}" = "${current%|*}" ] && [ "$previous" != "$current" ]
+}
+
 case $mode in
+  snapshot)
+    changed_since_snapshot
+    exit 0
+    ;;
   save)
     text=$(printf '%s' "$input" | jq -r '.text // ""')
     [ -n "$text" ] && [ -n "$conversation" ] || exit 0
@@ -12,12 +48,16 @@ case $mode in
     exit 0
     ;;
   followup)
+    changed=false
+    changed_since_snapshot && changed=true
     [ -n "$conversation" ] && [ -f "$state_directory/$conversation" ] || exit 0
     reply=$(cat "$state_directory/$conversation")
     rm -f "$state_directory/$conversation"
     [ "$(printf '%s' "$input" | jq -r '"\(.status // "") \(.loop_count // "")"')" = 'completed 0' ] || exit 0
     ;;
   *)
+    changed=false
+    changed_since_snapshot && changed=true
     [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = true ] && exit 0
     reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // ""')
     ;;
@@ -48,6 +88,10 @@ case $last in
   *) problems="${problems}End the reply with a line that starts with **Status:**; nothing may follow it. " ;;
 esac
 
+if [ "$changed" = true ] && ! printf '%s\n' "$outside_fences" | grep -q '^\*\*Checks:\*\*'; then
+  problems="${problems}A file outside intent/ changed in this turn and the reply has no **Checks:** section. Run the checks the project names and add **Checks:** with each command and the lines of its output that show the result, or with each check that could not run and why. "
+fi
+
 [ -z "$problems" ] && exit 0
 jq -n --arg mode "$mode" --arg reason "${problems}Send the whole reply again." \
   'if $mode == "followup" then {followup_message:$reason} else {decision:"block",reason:$reason} end'

package/templates/base/plugins/sdlc/claude-code/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "timeout": 10,
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" snapshot"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/SKILL.md

@@ -49,7 +49,7 @@ For example, the person writes "who must approve pull request #7 of https://host
 
 **Steps:** <only when the session has no task-list tool, and never for the `question` playbook. One line for each numbered step of the playbook: `1. <the step, copied word for word>: done | open | skip: <reason>`. When the turn ran more than one playbook, one list for each, under its file name on a line of its own, such as `playbooks/build.md`.>
 
-**Checks:** <only when a step ran checks, and never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output.>
+**Checks:** <when a step ran checks, and always when the turn changed a file outside `intent/`, whichever playbook ran. Otherwise never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output. For a check that could not run, the check and why.>
 
 <What the current step produces: the round of questions, or the whole draft. For a question or a request no row fits, the answer.>
 

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/playbooks/maintain.md

@@ -13,6 +13,6 @@ This playbook starts from a finding such as an alert, a monitoring ticket, a fai
    - Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
    - When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
 5. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When you cannot open a pull request from this session, say so and give the pushed branch's name.
-6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
+6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, comments on it with when the finding is scheduled and leaves it open, or closes it to dismiss it. An open pull request with no such comment is undecided: say so, and never report it as scheduled. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
 
 **Next:** `playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc:sdlc-mode` with the intent's path.

package/templates/base/plugins/sdlc/claude-code/skills/sdlc-mode/playbooks/review.md

@@ -1,6 +1,6 @@
 # Review phase: review the pull request and drive it to green
 
-1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
+1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment. When a pull request exists and this session cannot post on it, the findings are not in the pull request's history: the **Status** line says that the findings are not on the pull request and that a person posts them there, step 3 stays `open`, and you do not report the review as done.
 2. Review with a fresh context. Start a subagent that has not seen the work. Give it only the diff, `REVIEW.md`, the change's `intent/<change>/spec.md` and `plan.md`, and the four policy files in force, found as `playbooks/design.md` step 2 says. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. A change that is not a fix, an intent, or a spec, and has no `spec.md` or no `plan.md`, is itself a finding.
 3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge. When a finding flags a mistake that an earlier review of this project flagged too, its correction goes into the project's agent instructions as part of this review: in the push of step 4, or, on a pull request or a branch this session did not create, as the exact line in this comment.
 4. On a pull request or a branch that this session did not create, change nothing and push nothing. Skip the rest of this step, and in step 5 only read and answer. Otherwise, fix every Important finding. Run the checks the project's agent instructions name, and push. Answer each finding you do not fix with the reason.

package/templates/base/plugins/sdlc/claude-code/skills/setup-sdlc/SKILL.md

@@ -46,6 +46,8 @@ Do these steps in order. Run again with the same answers, the skill writes the s
    - `2. Owners: not done. .github/CODEOWNERS still holds the placeholder.`
    - `3. Repository settings: a person checks this. They live on the host, not in the repository.`
 
+   Report code owners, the ruleset of the default branch, and the OpenTelemetry export each on a line of its own, with what `SETUP.md` says the step needs, such as `Ruleset of main: a person checks this. It needs a repository admin, and in a private repository GitHub Pro, Team, or Enterprise.` A step that is not done fails no check.
+
 7. **Do the `not done` steps an agent can do:** a step whose whole work is editing a file of the repository with values the repository or the request already gives. Do not redo a `done` step. Do not edit a file the project's rules or agent settings reserve for a person, such as rules, hooks, lint, format, and commit configuration, and the agent settings themselves; list it with the exact new text and the file it goes in. Commit nothing. After each step, run its **Check** again and report the result.
 8. **List the steps a person does outside the repository,** each with who does it, from `SETUP.md`, and the full URL of the page where it is done when `SETUP.md` or the repository names one.
 9. **Write the reply** by the reply rules in `../sdlc-mode/SKILL.md`. After them, in this order: the budget line and the four role lines as written; each step of `SETUP.md` with its state; what you did; what a person does.

package/templates/base/plugins/sdlc/cursor/hooks/check-reply-shape.sh

@@ -3,8 +3,44 @@ command -v jq > /dev/null || exit 0
 mode=${1:-}
 input=$(cat)
 state_directory=${TMPDIR:-/tmp}/sdlc-reply-shape
-conversation=$(printf '%s' "$input" | jq -r '.conversation_id // ""' | tr -cd 'A-Za-z0-9_-')
+conversation=$(printf '%s' "$input" | jq -r '.conversation_id // .session_id // ""')
+conversation=${conversation:+$(printf '%s' "$conversation" | cksum | tr ' ' '-')}
+project=$(printf '%s' "$input" | jq -r '.cwd // .workspace_roots[0] // ""')
+snapshot_file=$state_directory/$conversation.files
+
+# A copy of the index and a scratch object store keep the project's own Git data unwritten.
+snapshot() {
+  [ -n "$project" ] && [ -n "$conversation" ] || return 1
+  repository=$(git -C "$project" rev-parse --show-toplevel 2> /dev/null) || return 1
+  index=$(git -C "$repository" rev-parse --git-path index) || return 1
+  objects=$(git -C "$repository" rev-parse --git-path objects) || return 1
+  case $index in /*) ;; *) index=$repository/$index ;; esac
+  case $objects in /*) ;; *) objects=$repository/$objects ;; esac
+  scratch=$state_directory/$conversation.git
+  rm -rf "$scratch"
+  mkdir -p "$scratch/objects" || return 1
+  cp "$index" "$scratch/index" 2> /dev/null
+  content=$(
+    export GIT_INDEX_FILE="$scratch/index" GIT_OBJECT_DIRECTORY="$scratch/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$objects"
+    git -C "$repository" add -A -- ':(top)' ':(top,exclude)intent' 2> /dev/null
+    git -C "$repository" ls-files -s -- ':(top)' ':(top,exclude)intent' | cksum
+  )
+  rm -rf "$scratch"
+  printf '%s|%s' "$repository" "$content"
+}
+
+changed_since_snapshot() {
+  current=$(snapshot) || return 1
+  previous=$(cat "$snapshot_file" 2> /dev/null)
+  printf '%s' "$current" > "$snapshot_file"
+  [ "${previous%|*}" = "${current%|*}" ] && [ "$previous" != "$current" ]
+}
+
 case $mode in
+  snapshot)
+    changed_since_snapshot
+    exit 0
+    ;;
   save)
     text=$(printf '%s' "$input" | jq -r '.text // ""')
     [ -n "$text" ] && [ -n "$conversation" ] || exit 0
@@ -12,12 +48,16 @@ case $mode in
     exit 0
     ;;
   followup)
+    changed=false
+    changed_since_snapshot && changed=true
     [ -n "$conversation" ] && [ -f "$state_directory/$conversation" ] || exit 0
     reply=$(cat "$state_directory/$conversation")
     rm -f "$state_directory/$conversation"
     [ "$(printf '%s' "$input" | jq -r '"\(.status // "") \(.loop_count // "")"')" = 'completed 0' ] || exit 0
     ;;
   *)
+    changed=false
+    changed_since_snapshot && changed=true
     [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = true ] && exit 0
     reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // ""')
     ;;
@@ -48,6 +88,10 @@ case $last in
   *) problems="${problems}End the reply with a line that starts with **Status:**; nothing may follow it. " ;;
 esac
 
+if [ "$changed" = true ] && ! printf '%s\n' "$outside_fences" | grep -q '^\*\*Checks:\*\*'; then
+  problems="${problems}A file outside intent/ changed in this turn and the reply has no **Checks:** section. Run the checks the project names and add **Checks:** with each command and the lines of its output that show the result, or with each check that could not run and why. "
+fi
+
 [ -z "$problems" ] && exit 0
 jq -n --arg mode "$mode" --arg reason "${problems}Send the whole reply again." \
   'if $mode == "followup" then {followup_message:$reason} else {decision:"block",reason:$reason} end'

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

@@ -1,6 +1,11 @@
 {
   "version": 1,
   "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "sh \"${CURSOR_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" snapshot"
+      }
+    ],
     "afterAgentResponse": [
       {
         "command": "sh \"${CURSOR_PLUGIN_ROOT}/hooks/check-reply-shape.sh\" save"

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/SKILL.md

@@ -49,7 +49,7 @@ For example, the person writes "who must approve pull request #7 of https://host
 
 **Steps:** <only when the session has no task-list tool, and never for the `question` playbook. One line for each numbered step of the playbook: `1. <the step, copied word for word>: done | open | skip: <reason>`. When the turn ran more than one playbook, one list for each, under its file name on a line of its own, such as `playbooks/build.md`.>
 
-**Checks:** <only when a step ran checks, and never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output.>
+**Checks:** <when a step ran checks, and always when the turn changed a file outside `intent/`, whichever playbook ran. Otherwise never for the `question` playbook. Each command, then the lines of its output that show the result, copied from the output. For a check that could not run, the check and why.>
 
 <What the current step produces: the round of questions, or the whole draft. For a question or a request no row fits, the answer.>
 

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/playbooks/maintain.md

@@ -13,6 +13,6 @@ This playbook starts from a finding such as an alert, a monitoring ticket, a fai
    - Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
    - When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
 5. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as the opening paragraph of `playbooks/open-pr.md` says for branches and pull requests. When you cannot open a pull request from this session, say so and give the pushed branch's name.
-6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
+6. **Gate: the service owner triages the finding.** The service owner merges the pull request to fix the finding now, comments on it with when the finding is scheduled and leaves it open, or closes it to dismiss it. An open pull request with no such comment is undecided: say so, and never report it as scheduled. A dismissal tunes the bands: the service owner adjusts `bands.yaml` so the same noise raises fewer findings. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `playbooks/review.md` says, and wait.
 
 **Next:** `playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc:sdlc-mode` with the intent's path.

package/templates/base/plugins/sdlc/cursor/skills/sdlc-mode/playbooks/review.md

@@ -1,6 +1,6 @@
 # Review phase: review the pull request and drive it to green
 
-1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
+1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment. When a pull request exists and this session cannot post on it, the findings are not in the pull request's history: the **Status** line says that the findings are not on the pull request and that a person posts them there, step 3 stays `open`, and you do not report the review as done.
 2. Review with a fresh context. Start a subagent that has not seen the work. Give it only the diff, `REVIEW.md`, the change's `intent/<change>/spec.md` and `plan.md`, and the four policy files in force, found as `playbooks/design.md` step 2 says. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. A change that is not a fix, an intent, or a spec, and has no `spec.md` or no `plan.md`, is itself a finding.
 3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge. When a finding flags a mistake that an earlier review of this project flagged too, its correction goes into the project's agent instructions as part of this review: in the push of step 4, or, on a pull request or a branch this session did not create, as the exact line in this comment.
 4. On a pull request or a branch that this session did not create, change nothing and push nothing. Skip the rest of this step, and in step 5 only read and answer. Otherwise, fix every Important finding. Run the checks the project's agent instructions name, and push. Answer each finding you do not fix with the reason.

package/templates/base/plugins/sdlc/cursor/skills/setup-sdlc/SKILL.md

@@ -46,6 +46,8 @@ Do these steps in order. Run again with the same answers, the skill writes the s
    - `2. Owners: not done. .github/CODEOWNERS still holds the placeholder.`
    - `3. Repository settings: a person checks this. They live on the host, not in the repository.`
 
+   Report code owners, the ruleset of the default branch, and the OpenTelemetry export each on a line of its own, with what `SETUP.md` says the step needs, such as `Ruleset of main: a person checks this. It needs a repository admin, and in a private repository GitHub Pro, Team, or Enterprise.` A step that is not done fails no check.
+
 7. **Do the `not done` steps an agent can do:** a step whose whole work is editing a file of the repository with values the repository or the request already gives. Do not redo a `done` step. Do not edit a file the project's rules or agent settings reserve for a person, such as rules, hooks, lint, format, and commit configuration, and the agent settings themselves; list it with the exact new text and the file it goes in. Commit nothing. After each step, run its **Check** again and report the result.
 8. **List the steps a person does outside the repository,** each with who does it, from `SETUP.md`, and the full URL of the page where it is done when `SETUP.md` or the repository names one.
 9. **Write the reply** by the reply rules in `../sdlc-mode/SKILL.md`. After them, in this order: the budget line and the four role lines as written; each step of `SETUP.md` with its state; what you did; what a person does.

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,