create-afe-project 0.0.0-stage → 2.0.0

package/template/scripts/check.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# All checks: the single local entry point (AGENTS.md, section 6). Runs every part even when an
+# earlier one fails, then reports which parts failed.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+failed=()
+run() {
+  echo "#### $1"
+  "$@" || failed+=("$1")
+}
+run scripts/check-docs.sh
+run scripts/check-decisions.sh
+run scripts/check-template.sh
+run scripts/check-project.sh
+
+if [ "${#failed[@]}" -gt 0 ]; then
+  echo "#### failed: ${failed[*]}"
+  exit 1
+fi
+echo "#### all checks passed"

package/template/scripts/env.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# The environment contract (docs/README.md, "Environment commands"; docs/contributing.md,
+# section 1): one entry point for the commands an agent needs to set up, check, test end to end,
+# and reset the project. `check` is scripts/check.sh; the others are the project's commands in
+# .claude/harness.conf (SETUP, CHECK_FAST, E2E, RESET), run from the repository root with no
+# stdin. A command that is not set prints SKIP and exits 0; otherwise the exit code is the
+# command's, so a failure is machine-readable.
+#
+# Usage: scripts/env.sh setup|check|fast|e2e|reset
+set -uo pipefail
+cd "$(dirname "$0")/.."
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh
+
+case "${1:-}" in
+  setup) key=SETUP ;;
+  check) echo "== env check: scripts/check.sh"; exec scripts/check.sh < /dev/null ;;
+  fast) key=CHECK_FAST ;;
+  e2e) key=E2E ;;
+  reset) key=RESET ;;
+  *) echo "usage: scripts/env.sh setup|check|fast|e2e|reset" >&2; exit 2 ;;
+esac
+cmd=$(conf_get "$key")
+if [ -z "$cmd" ]; then
+  echo "SKIP: $key is not set in .claude/harness.conf"
+  exit 0
+fi
+echo "== env $1: $cmd"
+bash -c "$cmd" < /dev/null

package/template/scripts/gen-decisions-index.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Prints the decision index from the front matter of the records (docs/documentation-rules.md,
+# section 2).
+# Usage: scripts/gen-decisions-index.sh > docs/decisions/README.md
+# scripts/check-decisions.sh fails when the committed index differs from this output.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# Prints front-matter field $1 of the record read from stdin, without surrounding quotes.
+field() {
+  tr -d '\r' | awk -v k="$1" 'NR==1 && $0!="---" {exit} NR>1 && $0=="---" {exit}
+       NR>1 && index($0, k ":")==1 {
+         v = substr($0, length(k) + 2); sub(/^[[:space:]]+/, "", v); sub(/[[:space:]]+$/, "", v)
+         if (v ~ /^".*"$/) v = substr(v, 2, length(v) - 2)
+         print v; exit}'
+}
+
+# Prints the first level-one heading after the front matter.
+title() {
+  awk 'NR==1 && $0=="---" {fm=1; next} fm && $0=="---" {fm=0; next}
+       !fm && /^# / {sub(/^# /, ""); print; exit}'
+}
+
+# Prints $1 as a table cell: "–" when empty, pipes escaped.
+cell() {
+  local v="${1:-}"
+  [ -n "$v" ] || v="–"
+  printf '%s' "${v//|/\\|}"
+}
+
+shopt -s nullglob
+records=(docs/decisions/[0-9][0-9][0-9][0-9]-*.md)
+
+cat <<'EOF'
+# Decision records
+
+Generated by `scripts/gen-decisions-index.sh` from the front matter of the records; do not edit
+by hand. Read this index first and open a record only when the task needs it. Which decisions get
+a record, and where the other owner decisions live:
+[`documentation-rules.md`](../documentation-rules.md), sections 3 and 5.
+
+EOF
+if [ "${#records[@]}" -eq 0 ]; then
+  echo "No records yet."
+  exit 0
+fi
+cat <<'EOF'
+| ADR | Status | Scope | Decision | Summary | Supersedes |
+| --- | --- | --- | --- | --- | --- |
+EOF
+for f in "${records[@]}"; do
+  name=$(basename "$f")
+  printf '| [%s](%s) | %s | %s | %s | %s | %s |\n' "${name:0:4}" "$name" \
+    "$(cell "$(field status < "$f")")" "$(cell "$(field scope < "$f")")" \
+    "$(cell "$(title < "$f")")" "$(cell "$(field summary < "$f")")" \
+    "$(cell "$(field supersedes < "$f" | tr -d '[]')")"
+done

package/template/scripts/gen-settings.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Generates .claude/settings.json (docs/documentation-rules.md, section 9) from the template's
+# .claude/settings.template.json and the project's .claude/settings.project.json: objects merge
+# key by key, arrays are joined without duplicates (the template's entries first), and for any
+# other value the project's wins. The project's top-level "remove" holds entries to take out of
+# the template's arrays, such as {"remove": {"permissions": {"deny": ["Read(**/.env.*)"]}}}.
+# Claude Code reads only the generated file.
+#
+# Usage: scripts/gen-settings.sh [--check]
+#   --check  write nothing; fail when .claude/settings.json differs from the merge.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+command -v node >/dev/null || { echo "gen-settings: Node.js is required" >&2; exit 2; }
+exec node scripts/lib/json.mjs settings ${1:+"$1"}

package/template/scripts/lib/classes.sh

@@ -0,0 +1,89 @@
+# Sourced by scripts/check-decisions.sh. The path classes of docs/documentation-rules.md,
+# section 8: approval, high, gate, normal, low; a path takes the highest class that applies.
+# - approval, built in: AGENTS.md, the template-owned files of .template/owned.txt, the generated
+#   .template/owned.sha256, the answers file (.afe-answers.json, or the legacy
+#   .copier-answers.yml), and .claude/settings.json, the map
+#   docs/README.md, .claude/path-classes, .claude/settings.project.json, .mcp.json, the glob
+#   lines of a legacy .claude/protected-paths, any decision record that exists on the base, and
+#   any decision record whose status is not `proposed`;
+# - then every `<class> <glob>` line of .claude/path-classes that matches;
+# - a path that nothing matches is low when it is Markdown or generated, otherwise normal.
+
+classes_file=.claude/path-classes
+
+class_rank() {
+  case "$1" in approval) echo 5 ;; high) echo 4 ;; gate) echo 3 ;; normal) echo 2 ;; low) echo 1 ;; *) echo 0 ;; esac
+}
+
+# True when $1 matches a glob line of the list file $2; '#' starts a comment.
+glob_listed() {
+  local pat
+  [ -f "$2" ] || return 1
+  while IFS= read -r pat || [ -n "$pat" ]; do
+    case "$pat" in ''|'#'*) continue ;; esac
+    # shellcheck disable=SC2254
+    case "$1" in $pat) return 0 ;; esac
+  done < "$2"
+  return 1
+}
+
+# True when path $1 is an approval path by a built-in rule; $2 is the base commit.
+builtin_approval() {
+  case "$1" in
+    AGENTS.md|.template/owned.sha256|.afe-answers.json|.copier-answers.yml|.claude/settings.json|docs/README.md|\
+    .claude/path-classes|.claude/settings.project.json|.mcp.json) return 0 ;;
+    docs/decisions/README.md) return 1 ;;
+    docs/decisions/[0-9][0-9][0-9][0-9]-*.md)
+      git cat-file -e "$2:$1" 2>/dev/null && return 0
+      [ -f "$1" ] && ! head -n 8 "$1" | grep -q -E '^status:[[:space:]]*proposed' && return 0 ;;
+  esac
+  glob_listed "$1" .template/owned.txt || glob_listed "$1" .claude/protected-paths
+}
+
+# class_of <path> <base commit> [content]: prints the class of the path. With "content", approval
+# is left out: the class of what the path contains, which decides its review.
+class_of() {
+  local best=0 name= cls pat r
+  if [ "${3:-}" != content ] && builtin_approval "$1" "$2"; then echo approval; return; fi
+  if [ -f "$classes_file" ]; then
+    while read -r cls pat || [ -n "$cls" ]; do
+      case "$cls" in ''|'#'*) continue ;; esac
+      [ -n "$pat" ] || continue
+      [ "${3:-}" = content ] && [ "$cls" = approval ] && continue
+      # shellcheck disable=SC2254
+      case "$1" in $pat) ;; *) continue ;; esac
+      r=$(class_rank "$cls")
+      [ "$r" -gt "$best" ] && best=$r name=$cls
+    done < "$classes_file"
+  fi
+  if [ -z "$name" ]; then
+    case "$1" in
+      *.md|.template/owned.sha256|.afe-answers.json|.copier-answers.yml|.claude/settings.json) name=low ;;
+      *) name=normal ;;
+    esac
+  fi
+  echo "$name"
+}
+
+# review_level <base commit> <path>...: the review before the pull request that the paths need,
+# by their highest content class: santa (high), one (gate, normal), or none (low). A template
+# update needs none, because the template repository reviewed it: a change of
+# the answers file whose other paths are all template-owned, generated, or seeded.
+review_level() {
+  local mb="$1" p c best=1 update=1 answers=0
+  shift
+  for p in "$@"; do
+    case "$p" in
+      .afe-answers.json|.copier-answers.yml) answers=1 ;;
+      AGENTS.md|.template/owned.sha256|.claude/settings.json|docs/decisions/README.md) ;;
+      README.md|CLAUDE.md|.gitignore|docs/README.md|.claude/path-classes|.claude/harness.conf|\
+      .claude/settings.project.json|.claude/protected-paths) ;;
+      *) glob_listed "$p" .template/owned.txt || update=0 ;;
+    esac
+    c=$(class_rank "$(class_of "$p" "$mb" content)")
+    [ "$c" -gt "$best" ] && best=$c
+  done
+  if [ "$#" -eq 0 ] || { [ "$update" = 1 ] && [ "$answers" = 1 ]; } || [ "$best" -le 1 ]; then echo none
+  elif [ "$best" -ge 4 ]; then echo santa
+  else echo one; fi
+}

package/template/scripts/lib/git-base.sh

@@ -0,0 +1,25 @@
+# Sourced by scripts/check-decisions.sh, scripts/fail-without-change.sh, the Stop hooks
+# .claude/hooks/stop-check-docs.sh and .claude/hooks/stop-check-fast.sh, and
+# .claude/hooks/session-start.sh.
+# resolve_base [ref] prints the commit that the current change is compared with:
+# - with a ref: the merge base of that ref and HEAD; an unknown ref is an error (status 2);
+# - without: the merge base with the first of origin/HEAD, origin/main, and main that exists (the
+#   branch a pull request goes into, never the current branch's own upstream); else HEAD (only
+#   uncommitted changes count); else, in a repository without commits, the empty tree.
+resolve_base() {
+  local ref
+  if [ -n "${1:-}" ]; then
+    git rev-parse --verify -q "$1^{commit}" >/dev/null || { echo "unknown base ref '$1'" >&2; return 2; }
+    git merge-base "$1" HEAD
+    return
+  fi
+  for ref in origin/HEAD origin/main main; do
+    git rev-parse --verify -q "$ref^{commit}" >/dev/null 2>&1 || continue
+    git merge-base "$ref" HEAD 2>/dev/null && return 0
+  done
+  if git rev-parse --verify -q HEAD >/dev/null; then
+    git rev-parse HEAD
+  else
+    git hash-object -t tree /dev/null
+  fi
+}

package/template/scripts/lib/harness-conf.sh

@@ -0,0 +1,48 @@
+# Sourced by the scripts that read .claude/harness.conf (docs/contributing.md, section 3).
+# conf_get KEY [default]: prints the value of the last `KEY=value` line of the file, without
+# surrounding quotes, or the default when the key is missing or empty. The file is read, never run.
+conf_get() {
+  local v=
+  [ -f .claude/harness.conf ] &&
+    v=$(tr -d '\r' < .claude/harness.conf | awk -v k="$1" 'index($0, k "=") == 1 {v = substr($0, length(k) + 2)} END {print v}')
+  case "$v" in \"*\") v=${v#\"}; v=${v%\"} ;; \'*\') v=${v#\'}; v=${v%\'} ;; esac
+  printf '%s' "${v:-${2:-}}"
+}
+
+# matching_files <globs>: prints the tracked and untracked files that match one of the
+# space-separated shell globs, in which * also matches /.
+matching_files() {
+  local f g
+  { git ls-files; git ls-files --others --exclude-standard; } | sort -u | while IFS= read -r f; do
+    set -f
+    for g in $1; do
+      # shellcheck disable=SC2254
+      case "$f" in $g) printf '%s\n' "$f"; break ;; esac
+    done
+    set +f
+  done
+}
+
+# The Ralph loop's cap in the Stop hooks (docs/contributing.md, section 3). ralph_block <name>
+# <message>: below RALPH_MAX_ITERATIONS failing stops of hook <name>, prints the message and
+# exits 2, which sends the agent back to fix it; at the cap, prints the message and that the cap
+# is reached, resets the count, and exits 0, so the agent stops and reports the failure.
+# ralph_pass <name>: resets the count when the hook's check passes. The counts live in the git
+# directory, one file per hook and Claude Code session (RALPH_SESSION, the hook input's
+# session_id), so an interrupted loop does not shorten the next one.
+ralph_count_file() { printf '%s/ralph-stops-%s-%s' "$(git rev-parse --git-dir 2>/dev/null || echo /tmp)" "${RALPH_SESSION:-none}" "$1"; }
+ralph_block() {
+  local f n cap
+  f=$(ralph_count_file "$1")
+  n=$(( $(cat "$f" 2>/dev/null || echo 0) + 1 ))
+  cap=$(conf_get RALPH_MAX_ITERATIONS 5)
+  printf '%s\n' "$2" >&2
+  if [ "$n" -ge "$cap" ]; then
+    rm -f "$f"
+    printf 'Ralph loop cap of %s reached: stop now and report the failing command and its output (docs/contributing.md, section 3).\n' "$cap" >&2
+    exit 0
+  fi
+  echo "$n" > "$f"
+  exit 2
+}
+ralph_pass() { rm -f "$(ralph_count_file "$1")"; }

package/template/scripts/lib/json.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// JSON for the hooks and scripts (docs/documentation-rules.md, section 9), with Node.js only.
+//
+// Usage: node scripts/lib/json.mjs <command> [arguments]
+//   fields <path>...         read JSON from stdin; print the value at each dotted path, each
+//                            followed by a NUL byte, an empty string when missing; the path
+//                            @secret prints the kind of the first known token format in the text
+//                            a PreToolUse input writes (content, new_string, edits, command)
+//   get <path> [default]     read JSON from stdin; print the value at the path, or the default
+//   ask <reason>             print the PreToolUse decision that asks the owner, with the reason
+//   deny <reason>            print the PreToolUse decision that denies the action, with the reason
+//   settings [--check]       merge .claude/settings.template.json and .claude/settings.project.json
+//                            into .claude/settings.json (scripts/gen-settings.sh); with --check,
+//                            write nothing and exit 1 when the file is missing or stale
+//   hooks                    print the command of every hook in .claude/settings.json, one per line
+//   prs <since> <separator>  read `gh pr list --json number,createdAt,mergedAt,body` from stdin;
+//                            print the count listed and the count merged before <since> on the
+//                            first line, then for each pull request merged on or after <since> a
+//                            line "<separator>PR <number> <hours to merge>" and its body
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+const stdin = () => readFileSync(0, 'utf8');
+const at = (obj, path) => path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+const text = (v) => (v == null ? '' : typeof v === 'string' ? v : JSON.stringify(v));
+
+function parse(input) {
+  try {
+    return JSON.parse(input || 'null');
+  } catch {
+    return null;
+  }
+}
+
+// High-confidence token formats; a match asks the owner, it does not prove a live secret.
+const SECRETS = [
+  ['AWS access key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ['GitHub token', /\bgh[pousr]_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{60,}/],
+  ['GitLab token', /\bglpat-[A-Za-z0-9_-]{20,}/],
+  ['Slack token', /\bxox[abposr]-[A-Za-z0-9-]{10,}/],
+  ['Stripe live key', /\b[rs]k_live_[A-Za-z0-9]{20,}/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['Anthropic API key', /\bsk-ant-[A-Za-z0-9_-]{20,}/],
+  ['OpenAI API key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{40,}/],
+  ['npm token', /\bnpm_[A-Za-z0-9]{36}\b/],
+  ['private key', /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY(?: BLOCK)?-----/],
+];
+
+function secret(input) {
+  const t = input?.tool_input ?? {};
+  const texts = [t.content, t.new_string, t.command, ...(Array.isArray(t.edits) ? t.edits.map((e) => e?.new_string) : [])];
+  const text = texts.filter((x) => typeof x === 'string').join('\n');
+  return SECRETS.find(([, re]) => re.test(text))?.[0] ?? '';
+}
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function equal(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((x, i) => equal(x, b[i]));
+  if (isObject(a) && isObject(b)) {
+    const ka = Object.keys(a);
+    return ka.length === Object.keys(b).length && ka.every((k) => k in b && equal(a[k], b[k]));
+  }
+  return false;
+}
+
+// Objects merge by key, arrays are a union in order without duplicates, anything else: b wins.
+function merge(a, b) {
+  if (isObject(a) && isObject(b)) {
+    const out = {};
+    for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      out[k] = k in a && k in b ? merge(a[k], b[k]) : k in b ? b[k] : a[k];
+    }
+    return out;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const out = [];
+    for (const x of [...a, ...b]) if (!out.some((y) => equal(x, y))) out.push(x);
+    return out;
+  }
+  return b;
+}
+
+// Takes out of a what r names: keys recurse, array elements equal to one of r are removed.
+function drop(a, r) {
+  if (isObject(a) && isObject(r)) {
+    const out = { ...a };
+    for (const k of Object.keys(r)) if (k in out) out[k] = drop(out[k], r[k]);
+    return out;
+  }
+  if (Array.isArray(a) && Array.isArray(r)) return a.filter((x) => !r.some((y) => equal(x, y)));
+  return a;
+}
+
+function settings(check) {
+  const read = (f) => JSON.parse(readFileSync(f, 'utf8'));
+  const template = read('.claude/settings.template.json');
+  const project = existsSync('.claude/settings.project.json') ? read('.claude/settings.project.json') ?? {} : {};
+  const { remove = {}, ...rest } = project;
+  const merged = drop(merge(template, rest), remove);
+  const file = '.claude/settings.json';
+  if (check) {
+    if (!existsSync(file) || !equal(parse(readFileSync(file, 'utf8')), merged)) {
+      console.log('FAIL: .claude/settings.json is missing or stale; run scripts/gen-settings.sh');
+      process.exit(1);
+    }
+    return;
+  }
+  writeFileSync(file, `${JSON.stringify(merged, null, 2)}\n`);
+}
+
+function prs(since, sep) {
+  const list = parse(stdin()) ?? [];
+  const out = [`${list.length} ${list.filter((p) => p.mergedAt < since).length}`];
+  for (const p of list) {
+    if (!(p.mergedAt >= since)) continue;
+    const hours = (Date.parse(p.mergedAt) - Date.parse(p.createdAt ?? p.mergedAt)) / 3600000;
+    out.push(`${sep}PR ${p.number} ${hours}`, (p.body ?? '').replace(/\r/g, ''));
+  }
+  process.stdout.write(`${out.join('\n')}\n`);
+}
+
+const [command, ...args] = process.argv.slice(2);
+switch (command) {
+  case 'fields': {
+    const data = parse(stdin());
+    process.stdout.write(args.map((p) => `${p === '@secret' ? secret(data) : text(at(data, p))}\0`).join(''));
+    break;
+  }
+  case 'get': {
+    const v = at(parse(stdin()), args[0]);
+    process.stdout.write(v == null || v === '' ? (args[1] ?? '') : text(v));
+    break;
+  }
+  case 'ask':
+  case 'deny':
+    process.stdout.write(
+      `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: command, permissionDecisionReason: args[0] } })}\n`,
+    );
+    break;
+  case 'settings':
+    settings(args[0] === '--check');
+    break;
+  case 'hooks': {
+    const s = parse(existsSync('.claude/settings.json') ? readFileSync('.claude/settings.json', 'utf8') : '');
+    const commands = Object.values(s?.hooks ?? {})
+      .flat()
+      .flatMap((m) => m?.hooks ?? [])
+      .map((h) => h?.command)
+      .filter((c) => typeof c === 'string');
+    process.stdout.write(commands.map((c) => `${c.replace(/\n/g, ' ')}\n`).join(''));
+    break;
+  }
+  case 'prs':
+    prs(args[0] ?? '', args[1] ?? '\x1f');
+    break;
+  default:
+    console.error(`json.mjs: unknown command ${command ?? '(none)'}`);
+    process.exit(2);
+}

package/template/scripts/pr-metrics.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Aggregates the "Metrics" tables of merged pull requests (docs/contributing.md, section 3): the
+# findings of each sensor by class and how they were answered; the first-pass result of
+# scripts/check.sh; Ralph iterations, Santa rounds, owner interventions, and files outside the
+# scope, each with its median and maximum, since a distribution says more than a sum; the
+# regression rate (pull requests that repair another's behaviour); and the time from opening to
+# merge, which gh reports for every pull request. It measures which rules and checks earn their
+# keep, so that one that never fires can be proposed for removal. Only table rows inside
+# "## Metrics" are read; a pull request without that section counts for the time to merge only.
+# Needs the GitHub CLI (`gh`, signed in) and Node.js.
+#
+# Usage: scripts/pr-metrics.sh [--since YYYY-MM-DD] [--limit N] [--repo owner/name]
+#   --since  only pull requests merged on or after this date; default: all that gh lists
+#   --limit  how many merged pull requests gh lists, newest first; default 500. When all of them
+#            are in the period, older ones may be missing, and the script says so.
+#   --repo   the repository; default: the one of the current directory
+set -uo pipefail
+
+since= limit=500 repo=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --since) since="${2:?--since needs a date}"; shift 2 ;;
+    --limit) limit="${2:?--limit needs a number}"; shift 2 ;;
+    --repo) repo=(--repo "${2:?--repo needs owner/name}"); shift 2 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+command -v gh >/dev/null || { echo "pr-metrics: the GitHub CLI gh is required" >&2; exit 2; }
+command -v node >/dev/null || { echo "pr-metrics: Node.js is required" >&2; exit 2; }
+
+json=$(gh pr list --state merged --limit "$limit" --json number,createdAt,mergedAt,body ${repo[@]+"${repo[@]}"}) ||
+  { echo "pr-metrics: gh pr list failed" >&2; exit 2; }
+sep=$(printf '\037')
+feed=$(printf '%s' "$json" | node "$(dirname "$0")/lib/json.mjs" prs "$since" "$sep") || { echo "pr-metrics: cannot read the gh output" >&2; exit 2; }
+read -r listed outside <<< "${feed%%$'\n'*}"
+body=; case "$feed" in *$'\n'*) body=${feed#*$'\n'} ;; esac
+printf '%s\n' "$body" |
+  awk -F'|' -v sep="$sep" -v since="${since:-the first listed}" '
+    function add(name, v) { cnt[name]++; val[name, cnt[name]] = v + 0; sum[name] += v }
+    function stats(name,   i, j, t, n, a) {
+      n = cnt[name]; if (!n) return "none"
+      for (i = 1; i <= n; i++) a[i] = val[name, i]
+      for (i = 2; i <= n; i++) { t = a[i]; for (j = i - 1; j >= 1 && a[j] > t; j--) a[j + 1] = a[j]; a[j + 1] = t }
+      return sprintf("total %g, median %g, max %g, in %d pull requests", sum[name], (n % 2 ? a[(n + 1) / 2] : (a[n / 2] + a[n / 2 + 1]) / 2), a[n], n)
+    }
+    index($0, sep "PR ") == 1 { prs++; insec = 0; split(substr($0, length(sep) + 4), p, " "); add("hours to merge", sprintf("%.1f", p[2])); next }
+    /^## / { l = $0; sub(/[ \t]+$/, "", l); insec = (l == "## Metrics"); if (insec && !(prs in withm)) { withm[prs] = 1; nwith++ }; next }
+    !insec || !/^[ \t]*\|/ { next }
+    {
+      n = 0
+      for (i = 2; i < NF; i++) { c = $i; gsub(/^[ \t]+|[ \t]+$/, "", c); cell[++n] = c }
+      if (cell[1] == "Sensor" || cell[1] == "Measure" || cell[1] ~ /^:?-/) next
+      if (n == 6 && cell[2] ~ /^(blocker|suggestion)$/) {
+        k = cell[1] SUBSEP cell[2]
+        if (!(k in P)) order[++nk] = k
+        F[k] += cell[3]; X[k] += cell[4]; L[k] += cell[5]; D[k] += cell[6]; P[k]++
+        S[cell[1]] += cell[3]; if (!(cell[1] in seen)) { seen[cell[1]] = 1; sensors[++ns] = cell[1] }
+      } else if (n == 2) {
+        if (cell[1] == "First check.sh") { if (cell[2] ~ /^pass/) first_pass++; first_n++ }
+        else if (cell[1] == "Regression of") { reg_n++; if (cell[2] !~ /^none/) reg++ }
+        else if (cell[1] ~ /^(Ralph iterations|Santa rounds|Owner interventions|Files outside the scope)$/) add(tolower(cell[1]), cell[2])
+      }
+    }
+    END {
+      printf "== merged pull requests since %s: %d, with a Metrics section: %d\n", since, prs, nwith
+      printf "%-24s %-10s %6s %6s %6s %8s %4s\n", "sensor", "class", "found", "fixed", "limit", "declined", "PRs"
+      for (i = 1; i <= nk; i++) {
+        split(order[i], kk, SUBSEP)
+        printf "%-24s %-10s %6d %6d %6d %8d %4d\n", kk[1], kk[2], F[order[i]], X[order[i]], L[order[i]], D[order[i]], P[order[i]]
+      }
+      printf "first check.sh passed: %d of %d pull requests\n", first_pass, first_n
+      printf "regression rate: %d of %d pull requests repair another one\n", reg, reg_n
+      split("ralph iterations|santa rounds|owner interventions|files outside the scope|hours to merge", names, "|")
+      for (i = 1; i <= 5; i++) printf "%s: %s\n", names[i], stats(names[i])
+      for (i = 1; i <= ns; i++) if (S[sensors[i]] == 0) quiet = quiet (quiet == "" ? "" : ", ") sensors[i]
+      printf "== sensors without a finding in the period: %s\n", (quiet == "" ? "none" : quiet)
+    }'
+if [ "$listed" -ge "$limit" ] && [ "$outside" -eq 0 ]; then
+  echo "WARNING: gh listed $listed pull requests, the --limit, all in the period; older ones in the period may be missing. Raise --limit."
+fi

package/template/scripts/protect-branch.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Protects the default branch on GitHub (AGENTS.md, section 4) and applies the repository settings
+# the rules assume (docs/contributing.md, sections 1 and 3), with the GitHub CLI; run it once as a
+# repository admin, after the first push, and again with --require-base when that applies. A change
+# of repository settings is an owner action: an agent runs it only on the owner's explicit
+# instruction. In this order:
+# 1. Merge commits only, without squash and rebase merging, and "Automatically delete head
+#    branches": these work on every plan.
+# 2. Secret scanning with push protection: public repositories have them; a private one may need
+#    GitHub Advanced Security, so a refusal is reported and the script goes on.
+# 3. The repository ruleset "protect default branch": changes reach the default branch only through
+#    pull requests merged with a merge commit whose `check` (`docs` workflow) and `integrity`
+#    (`decisions` workflow) jobs pass, with --require-base also `base`, and only these: `readiness`
+#    signals and AI review is a sensor; it cannot be force-pushed or deleted. Updating a ruleset
+#    that requires `base` keeps it without --require-base while the fail-without-change workflow
+#    exists, drops it otherwise, and says which; a ruleset it cannot read stops the run unchanged.
+#    Rulesets need a public repository, or a GitHub plan that offers them for private ones;
+#    without one, the rule rests on the owner and review.
+#
+# Usage: scripts/protect-branch.sh [--dry-run] [--repo owner/name] [--require-base]
+#   --dry-run       print the settings and the ruleset as one JSON object and change nothing
+#   --repo          the repository; default: the one of the current directory
+#   --require-base  also require the `base` job of the fail-without-change workflow: use it once
+#                   that job has passed in CI on a pull request that changes a test, not as a SKIP;
+#                   the label `tests-pass-on-base` still lets a test that passes on the base through
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+dry= repo= base=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) dry=1; shift ;;
+    --repo) repo="${2:?--repo needs owner/name}"; shift 2 ;;
+    --require-base) base=1; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+if [ -n "$base" ] && [ ! -f .github/workflows/fail-without-change.yml ]; then
+  echo "protect-branch: --require-base needs the fail-without-change workflow, which this project does not have" >&2
+  exit 2
+fi
+
+name="protect default branch"
+plan() { node -e '
+  const [name, base] = process.argv.slice(1);
+  const checks = ["check", "integrity", ...(base ? ["base"] : [])].map((context) => ({ context }));
+  console.log(JSON.stringify({
+    repository: { allow_merge_commit: true, allow_squash_merge: false, allow_rebase_merge: false, delete_branch_on_merge: true },
+    security: { security_and_analysis: { secret_scanning: { status: "enabled" }, secret_scanning_push_protection: { status: "enabled" } } },
+    ruleset: {
+      name, target: "branch", enforcement: "active",
+      conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+      rules: [
+        { type: "deletion" },
+        { type: "non_fast_forward" },
+        { type: "pull_request", parameters: { required_approving_review_count: 0, dismiss_stale_reviews_on_push: false,
+            require_code_owner_review: false, require_last_push_approval: false, required_review_thread_resolution: false,
+            allowed_merge_methods: ["merge"] } },
+        { type: "required_status_checks", parameters: { strict_required_status_checks_policy: false,
+            required_status_checks: checks } },
+      ],
+    },
+  }, null, 2));' "$name" "$base"; }
+
+if [ -n "$dry" ]; then
+  plan
+  exit 0
+fi
+part() { plan | node -e 'console.log(JSON.stringify(JSON.parse(require("fs").readFileSync(0, "utf8"))[process.argv[1]]))' "$1"; }
+command -v gh > /dev/null || { echo "protect-branch: the GitHub CLI gh is required" >&2; exit 2; }
+[ -n "$repo" ] || repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+
+part repository | gh api --method PATCH "repos/$repo" --input - > /dev/null
+echo "== $repo: merge commits only, head branches deleted after the merge"
+if out=$(part security | gh api --method PATCH "repos/$repo" --input - 2>&1 > /dev/null); then
+  echo "== $repo: secret scanning and push protection on"
+else
+  printf '== %s: secret scanning and push protection not set; a private repository may need GitHub Advanced Security:\n%s\n' "$repo" "$out" >&2
+fi
+id=$(gh api "repos/$repo/rulesets" --jq ".[] | select(.name == \"$name\") | .id" | head -n 1)
+if [ -n "$id" ] && [ -z "$base" ]; then
+  contexts=$(gh api "repos/$repo/rulesets/$id" --jq '.rules[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context') || {
+    echo "protect-branch: cannot read the ruleset \"$name\" (id $id) of $repo; it is left unchanged" >&2
+    exit 1
+  }
+  if printf '%s\n' "$contexts" | grep -qx base; then
+    if [ -f .github/workflows/fail-without-change.yml ]; then
+      base=1
+      echo "== the ruleset \"$name\" requires \`base\`: kept (run with --require-base to say so)"
+    else
+      echo "== the ruleset \"$name\" requires \`base\`, which no workflow of this project reports: dropped" >&2
+    fi
+  fi
+fi
+if [ -n "$id" ]; then
+  part ruleset | gh api --method PUT "repos/$repo/rulesets/$id" --input - > /dev/null
+  echo "== updated the ruleset \"$name\" of $repo"
+else
+  part ruleset | gh api --method POST "repos/$repo/rulesets" --input - > /dev/null
+  echo "== created the ruleset \"$name\" of $repo"
+fi