create-afe-project 0.0.0-stage → 2.0.0

package/template/.claude/hooks/protect-docs.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# PreToolUse hook (Edit, Write, MultiEdit, Bash): a change to a path of class approval, and an
+# irreversible action, need an explicit owner instruction (AGENTS.md, section 4;
+# docs/documentation-rules.md, sections 8 and 9). Class approval are the template-owned files of
+# .template/owned.txt, the generated ownership manifest, answers file, and .claude/settings.json,
+# the documentation map, .claude/path-classes and its `approval <glob>` lines,
+# .claude/settings.project.json, .mcp.json, the glob lines of a legacy .claude/protected-paths,
+# ADRs that exist on main, and ADRs that are no longer `proposed`. The irreversible actions are the
+# commands that irreversible() below names. A target path is judged by the git repository that holds it when that
+# repository has .template/owned.txt, so a sibling worktree or another generated project is
+# guarded by its own paths; otherwise by the session's project (CLAUDE_PROJECT_DIR) when the path
+# is inside it; any other path is not guarded. A relative path of a shell command resolves
+# against the hook input's `cwd`. The hook turns such a change into a
+# permission prompt for the owner (`permissionDecision: ask`); in headless runs Claude Code denies
+# it. DOCS_GUARD=off in the Claude Code environment disables the guard for scripted owner-driven
+# runs, such as a template update. This is a guard against unreviewed changes, not a security
+# boundary: a command that hides the target path (for example inside a script file, behind a
+# variable, or in a directory changed by a script) is not detected.
+set -uo pipefail
+[ "${DOCS_GUARD:-on}" = "off" ] && exit 0
+
+# Without Node.js the hook cannot read the tool call; block it rather than allow everything.
+command -v node >/dev/null || { echo "protect-docs: Node.js is required (README.md, Checks)" >&2; exit 2; }
+json="$(cd "$(dirname "$0")/../.." && pwd)/scripts/lib/json.mjs"
+{ IFS= read -r -d '' tool; IFS= read -r -d '' cwd; IFS= read -r -d '' file_path; IFS= read -r -d '' cmd
+  IFS= read -r -d '' secret; } < <(node "$json" fields tool_name cwd tool_input.file_path tool_input.command @secret)
+[ -n "$cwd" ] && [ -d "$cwd" ] || cwd=$PWD
+project="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$project" ] && project=$(cd "$project" 2>/dev/null && pwd -P) || project=
+
+# True when $1 matches a line of the list file $2 (shell glob patterns; '#' starts a comment).
+listed() {
+  local pat
+  [ -f "$2" ] || return 1
+  while IFS= read -r pat; do
+    case "$pat" in ''|'#'*) continue ;; esac
+    # shellcheck disable=SC2254
+    case "$1" in $pat) return 0 ;; esac
+  done < "$2"
+  return 1
+}
+
+# Prints why $1 is protected, or nothing when it is not.
+protected_reason() {
+  local p="$1" abs rel dir rest seg norm climbed=1 root
+  case "$p" in /*) abs="$p" ;; *) abs="$cwd/$p" ;; esac
+  # Resolve "..", "//", and symbolic links in the part of the path that exists. In the part that
+  # does not exist yet, fold "." and "x/.."; a ".." left over climbs from the existing directory,
+  # and then the folded path is resolved once more, as it may enter another existing directory.
+  while [ -n "$climbed" ]; do
+    dir=$(dirname "$abs") rest=$(basename "$abs") norm= climbed=
+    while [ ! -d "$dir" ]; do rest="$(basename "$dir")/$rest"; dir=$(dirname "$dir"); done
+    dir=$(cd "$dir" && pwd -P) || return 0
+    while [ -n "$rest" ]; do
+      seg=${rest%%/*}
+      if [ "$seg" = "$rest" ]; then rest=; else rest=${rest#*/}; fi
+      case "$seg" in
+        ''|.) ;;
+        ..) if [ -z "$norm" ]; then dir=$(dirname "$dir") climbed=1
+            elif [ "${norm%/*}" = "$norm" ]; then norm=
+            else norm=${norm%/*}; fi ;;
+        *) norm=${norm:+$norm/}$seg ;;
+      esac
+    done
+    abs="$dir/$norm"
+  done
+  # The generated project that holds the path: its git repository when that has
+  # .template/owned.txt (a sibling worktree, another generated project), otherwise the session's
+  # project when the path is inside it (no git yet, a nested repository, a missing manifest).
+  root=$(git -C "$dir" rev-parse --show-toplevel 2>/dev/null) && root=$(cd "$root" && pwd -P) &&
+    [ -f "$root/.template/owned.txt" ] || root=$project
+  [ -n "$root" ] || return 0
+  rel="${abs#"$root"/}"
+  [ "$rel" != "$abs" ] || return 0
+  if [ "$rel" = AGENTS.md ]; then
+    echo "template-owned outside its project block; only the project block may change here"
+    return
+  fi
+  if approval_listed "$rel" "$root/.claude/path-classes"; then
+    echo "class approval in .claude/path-classes"
+    return
+  fi
+  if listed "$rel" "$root/.template/owned.txt"; then
+    echo "template-owned; change it in the template repository and update (docs/contributing.md, section 5)"
+    return
+  fi
+  case "$rel" in
+    .template/owned.sha256|.afe-answers.json|.copier-answers.yml)
+      echo "generated by a template update only" ;;
+    .claude/settings.json)
+      echo "generated by scripts/gen-settings.sh; change .claude/settings.project.json instead, with the owner" ;;
+    .claude/path-classes|.claude/protected-paths)
+      echo "the classes of paths, class approval" ;;
+    .claude/settings.project.json|.mcp.json)
+      echo "permissions and MCP servers, class approval" ;;
+    docs/README.md)
+      echo "documentation map; structure changes need the owner" ;;
+    docs/decisions/README.md)
+      ;; # generated by scripts/gen-decisions-index.sh; scripts/check-decisions.sh checks it
+    docs/decisions/*.md)
+      if git -C "$root" cat-file -e "origin/main:$rel" 2>/dev/null ||
+        { ! git -C "$root" rev-parse -q --verify origin/main >/dev/null && git -C "$root" cat-file -e "main:$rel" 2>/dev/null; }; then
+        echo "ADR that exists on main; only its status line changes (documentation-rules.md, section 5), otherwise supersede it with a new ADR"
+      elif [ -f "$abs" ] && ! head -n 8 "$abs" | grep -q -E '^status:[[:space:]]*proposed'; then
+        echo "ADR that is no longer proposed; immutable, supersede it with a new ADR"
+      fi ;;
+    *)
+      listed "$rel" "$root/.claude/protected-paths" && echo "listed in .claude/protected-paths" ;;
+  esac
+}
+
+# True when $1 matches an `approval <glob>` line of .claude/path-classes, file $2.
+approval_listed() {
+  local cls pat
+  [ -f "$2" ] || return 1
+  while read -r cls pat || [ -n "$cls" ]; do
+    [ "$cls" = approval ] && [ -n "$pat" ] || continue
+    # shellcheck disable=SC2254
+    case "$1" in $pat) return 0 ;; esac
+  done < "$2"
+  return 1
+}
+
+# Prints the paths a shell command can write, one per line: redirect targets in every segment, the
+# destination of cp, mv, install, and ln, the files of tee, rm, truncate, and touch, dd's of=, the
+# files of sed -i, perl -i, and git checkout, restore, rm, mv, and apply, and file-like tokens of an
+# interpreter (python, node, ruby, perl, bash, sh), also in the heredoc a python, node, ruby, or
+# perl reads; a heredoc on a line where a shell runs (`bash <<EOF`, `cat <<EOF | sh`,
+# `source /dev/stdin <<EOF`) is parsed as commands. A relative target is joined to
+# the directory of an earlier `cd DIR` with a literal DIR, and a git path argument to a literal
+# `git -C DIR`. The body of any other heredoc is text, not commands; `<<<`, `$((1 << n))`, and
+# `<<` inside quotes start no heredoc. Input files (<) and sources are not targets.
+write_targets() {
+  printf '%s\n' "$1" | awk '
+    function out(t) { if (t == "") return; if (t !~ /^\// && pre != "") t = pre "/" t; print t }
+    function emit_all(from,   x, na, A) { na = split(args, A, " "); for (x = from; x <= na; x++) out(A[x]) }
+    function files(text,   tmp) {
+      tmp = text
+      while (match(tmp, /[A-Za-z0-9_.\/-]*(\.(md|json|jsonc|toml|yml|yaml|sh|txt|sha256|jinja|conf|pem|key)|\.claude\/(protected-paths|path-classes)|\.env[A-Za-z0-9_.]*)/)) {
+        out(substr(tmp, RSTART, RLENGTH)); tmp = substr(tmp, RSTART + RLENGTH)
+      }
+    }
+    BEGIN { dir = "" }
+    hd != "" { l = $0; gsub(/^[ \t]+|[ \t]+$/, "", l); if (l == hd) { hd = ""; next }; if (hdint) { pre = dir; files($0) }; next }
+    {
+      line = $0; delim = ""
+      if (match(line, /<<-?[ \t]*["\047]?[A-Za-z_][A-Za-z0-9_]*/)) {
+        before = substr(line, 1, RSTART - 1); cand = substr(line, RSTART, RLENGTH)
+        dq = gsub(/"/, "\"", before); sq = gsub(/\047/, "\047", before)
+        if (before !~ /<$/ && before !~ /\$\(\([^)]*$/ && dq % 2 == 0 && sq % 2 == 0) {
+          delim = cand; sub(/^<<-?[ \t]*["\047]?/, "", delim)
+        }
+      }
+      n = split(line, segs, /[|;&]+/)
+      for (i = 1; i <= n; i++) {
+        s = segs[i]; tmp = s; pre = dir
+        m = split(s, w, /[ \t]+/); k = 1
+        while (k <= m && (w[k] == "" || w[k] ~ /^[A-Za-z_][A-Za-z0-9_]*=/ || w[k] == "sudo" || w[k] == "command")) k++
+        cmd = w[k]; sub(/.*\//, "", cmd)
+        if (cmd == "cd") {
+          d = w[k + 1]; gsub(/^["\047]+|["\047]+$/, "", d)
+          if (d ~ /[$`~*?]/ || d == "" || d == "-") { }
+          else if (d ~ /^\//) dir = d; else dir = (dir == "" ? d : dir "/" d)
+          continue
+        }
+        while (match(tmp, />>?[ \t]*["\047]?[A-Za-z0-9_.\/-]+/)) {
+          t = substr(tmp, RSTART, RLENGTH); sub(/^>>?[ \t]*["\047]?/, "", t); out(t)
+          tmp = substr(tmp, RSTART + RLENGTH)
+        }
+        if (cmd == "git" && w[k + 1] == "-C") {
+          d = w[k + 2]; gsub(/^["\047]+|["\047]+$/, "", d)
+          if (d !~ /[$`~*?]/) pre = (d ~ /^\// || dir == "") ? d : dir "/" d
+          for (x = k + 1; x + 2 <= m; x++) w[x] = w[x + 2]; m -= 2
+        }
+        gsub(/[0-9]*>>?[ \t]*["\047]?[^ \t]*/, "", s); gsub(/<<?-?[ \t]*[^ \t]*/, "", s)
+        if (cmd != "git") { m = split(s, w, /[ \t]+/); k = 1
+          while (k <= m && (w[k] == "" || w[k] ~ /^[A-Za-z_][A-Za-z0-9_]*=/ || w[k] == "sudo" || w[k] == "command")) k++ }
+        args = ""
+        for (j = k + 1; j <= m; j++) { a = w[j]; gsub(/^["\047]+|["\047]+$/, "", a); if (a !~ /^-/) args = args " " a }
+        if (cmd ~ /^(cp|mv|install|ln)$/) { na = split(args, A, " "); if (na) out(A[na]) }
+        else if (cmd ~ /^(tee|rm|truncate|touch)$/) emit_all(1)
+        else if (cmd == "dd") { na = split(args, A, " "); for (x = 1; x <= na; x++) if (sub(/^of=/, "", A[x])) out(A[x]) }
+        else if (cmd ~ /^(sed|perl)$/ && s ~ /[ \t]-[a-zA-Z]*i/) emit_all(1)
+        else if (cmd == "git" && w[k + 1] ~ /^(checkout|restore|rm|mv|apply)$/) emit_all(2)
+        if (cmd ~ /^(python3?|node|ruby|perl|bash|sh|zsh)$/) files(segs[i])
+        if (delim != "" && segs[i] ~ /<</) hdint = (cmd ~ /^(python3?|node|ruby|perl)$/)
+        if (cmd ~ /^(bash|sh|zsh|source|\.)$/) hdsh = 1
+      }
+      if (delim != "" && !hdsh) hd = delim
+      hdsh = 0
+    }'
+}
+
+# Prints the first irreversible action in a shell command, or nothing: in any segment, `git push`
+# (after git's global options such as -C DIR) with --force, --force-with-lease,
+# --force-if-includes, --delete, --mirror, --prune, or --tags, a short option that contains f or
+# d (-f, -uf, -d), a refspec that starts with + or :, or a tag (refs/tags/..., or v followed by a
+# digit, the form of a release); `gh pr merge`; `gh release create` or `gh release delete`;
+# `gh repo delete`; `gh workflow run`; `gh api` with the method DELETE; and publishing a package
+# or an image: `npm`, `pnpm`, `yarn`, `bun`, `cargo`, `poetry`, or `uv publish`, `twine upload`,
+# `gem push`, `dotnet nuget push`, `docker` or `podman push`.
+# With "push" as $2 it prints instead the words of the first `git push` that are not options:
+# the remote and the refspecs, one per line, or "-" alone when there are none.
+irreversible() {
+  printf '%s\n' "$1" | awk -v mode="${2:-}" '{
+    n = split($0, segs, /[|;&]+/)
+    for (i = 1; i <= n; i++) {
+      m = split(segs[i], w, /[ \t]+/); k = 1
+      while (k <= m && (w[k] == "" || w[k] ~ /^[A-Za-z_][A-Za-z0-9_]*=/ || w[k] == "sudo" || w[k] == "command")) k++
+      cmd = w[k]; sub(/.*\//, "", cmd)
+      s = k + 1
+      if (cmd == "git") while (s <= m && w[s] ~ /^-/) s += (w[s] == "-C" || w[s] == "-c") ? 2 : 1
+      sub1 = w[s]; sub2 = w[s + 1]
+      if (cmd == "git" && sub1 == "push") {
+        if (mode == "push") {
+          out = ""
+          for (j = s + 1; j <= m; j++) { a = w[j]; gsub(/^["\047]+|["\047]+$/, "", a); if (a != "" && a !~ /^-/) out = out a "\n" }
+          printf "%s", (out == "" ? "-\n" : out); exit
+        }
+        for (j = s + 1; j <= m; j++) {
+          a = w[j]; gsub(/^["\047]+|["\047]+$/, "", a)
+          if (a ~ /^--(force|force-with-lease|force-if-includes|delete|mirror|prune|tags)(=.*)?$/ || a ~ /^-[A-Za-z]*[fd][A-Za-z]*$/ || a ~ /^[+:]/ || a ~ /^(refs\/tags\/|v[0-9])/) {
+            print "git push " a; exit
+          }
+        }
+      }
+      if (mode == "push") continue
+      if (cmd == "gh" && ((sub1 == "pr" && sub2 == "merge") || (sub1 == "release" && sub2 ~ /^(create|delete)$/) || (sub1 == "repo" && sub2 == "delete") || (sub1 == "workflow" && sub2 == "run"))) {
+        print "gh " sub1 " " sub2; exit
+      }
+      if (cmd == "gh" && sub1 == "api") {
+        for (j = s + 1; j <= m; j++) if ((w[j] ~ /^(-X|--method)$/ && toupper(w[j + 1]) == "DELETE") || toupper(w[j]) ~ /^(-XDELETE|--METHOD=DELETE)$/) { print "gh api DELETE"; exit }
+      }
+      if ((cmd ~ /^(npm|pnpm|yarn|bun|cargo|poetry|uv)$/ && sub1 == "publish") || (cmd == "twine" && sub1 == "upload") || (cmd == "gem" && sub1 == "push") ||
+          (cmd ~ /^(docker|podman)$/ && sub1 == "push") || (cmd == "dotnet" && sub1 == "nuget" && sub2 == "push")) {
+        print cmd " " sub1 (cmd == "dotnet" ? " " sub2 : ""); exit
+      }
+    }
+  }'
+}
+
+# Prints the default branch when the shell command pushes to it, or nothing. Without a refspec,
+# `git push` pushes the current branch. A default branch that the remote does not have yet (the
+# first push of a new repository) is left to the owner's prompt, not denied.
+pushes_default() {
+  local words remote refs r dst def cur
+  words=$(irreversible "$1" push)
+  [ -n "$words" ] || return 0
+  def=$(git -C "$cwd" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null) && def=${def#origin/} || def=main
+  if [ "$words" = - ]; then refs=; remote=origin; else remote=$(printf '%s\n' "$words" | head -n 1); refs=$(printf '%s\n' "$words" | tail -n +2); fi
+  if [ -z "$refs" ]; then
+    cur=$(git -C "$cwd" symbolic-ref --quiet --short HEAD 2>/dev/null) || return 0
+    refs=$cur
+  fi
+  while IFS= read -r r; do
+    dst=${r#+}; dst=${dst##*:}; dst=${dst#refs/heads/}
+    [ "$dst" = HEAD ] && dst=$(git -C "$cwd" symbolic-ref --quiet --short HEAD 2>/dev/null)
+    if [ "$dst" = "$def" ]; then
+      git -C "$cwd" ls-remote --exit-code --heads "$remote" "$def" > /dev/null 2>&1 && echo "$def"
+      return 0
+    fi
+  done <<< "$refs"
+}
+
+ask_owner() {
+  node "$json" ask "Protected file: $1 ($2). Changing it needs an explicit owner instruction (AGENTS.md, section 4). Approve only if you asked for this change; otherwise the agent must report it as an open question."
+  exit 0
+}
+
+deny_push() {
+  node "$json" deny "Pushing to the default branch $1 is not allowed: changes reach it only through a pull request (AGENTS.md, section 4; docs/contributing.md, section 1). Push a branch and open a pull request instead."
+  exit 0
+}
+
+ask_action() {
+  node "$json" ask "Irreversible action: $1. It needs an explicit owner instruction (AGENTS.md, section 4; docs/documentation-rules.md, section 8). Approve only if you asked for it."
+  exit 0
+}
+
+# A push to the default branch is denied before anything asks: an approved prompt must never let
+# it through.
+if [ "$tool" = Bash ] && [ -n "$cmd" ]; then
+  branch=$(pushes_default "$cmd")
+  [ -n "$branch" ] && deny_push "$branch"
+fi
+
+# A known token format in what the call writes: secrets never go into the repository.
+if [ -n "$secret" ] && [[ "$tool" =~ ^(Edit|Write|MultiEdit|Bash)$ ]]; then
+  node "$json" ask "Possible secret ($secret) in this change. Secrets never go into the repository or a command line; use an environment variable or the CI secret store. Approve only if it is a placeholder or a test fixture."
+  exit 0
+fi
+
+case "$tool" in
+  Edit|Write|MultiEdit)
+    path=$file_path
+    [ -n "$path" ] || exit 0
+    reason=$(protected_reason "$path")
+    [ -n "$reason" ] && ask_owner "$path" "$reason"
+    ;;
+  Bash)
+    [ -n "$cmd" ] || exit 0
+    # Rewriting the manifest is how a local edit of a template-owned file would be hidden.
+    if printf '%s' "$cmd" | grep -q -E 'check-template\.sh[^|;&]*--write'; then
+      ask_owner ".template/owned.sha256" "generated by a template update only, via Bash"
+    fi
+    action=$(irreversible "$cmd")
+    [ -n "$action" ] && ask_action "$action"
+    targets=$(write_targets "$cmd")
+    for tok in $targets; do
+      reason=$(protected_reason "$tok")
+      [ -n "$reason" ] && ask_owner "$tok" "$reason, via Bash"
+    done
+    ;;
+esac
+exit 0

package/template/.claude/hooks/session-start.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# SessionStart hook: prints the local state of the work in progress, so that a new, resumed, or
+# compacted session starts from facts (docs/documentation-rules.md, section 7): the branch, the
+# base of the change (scripts/lib/git-base.sh) and the commits ahead of it, the count of
+# uncommitted and untracked files, unresolved merge conflicts, and each plan in docs/plans/ with
+# its review-by date, flagged when the date is past (section 5), past ones first. At most 10 lines
+# and local facts only: no network. Outside a git repository only the plans are shown. What it
+# cannot determine it leaves out; it always exits 0.
+set -uo pipefail
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" 2>/dev/null || exit 0
+lines=()
+
+if git rev-parse --git-dir > /dev/null 2>&1; then
+  if git rev-parse --verify -q HEAD > /dev/null; then
+    line="branch $(git symbolic-ref --short -q HEAD || printf 'none (detached at %s)' "$(git rev-parse --short HEAD)")"
+    # shellcheck source=scripts/lib/git-base.sh
+    if . scripts/lib/git-base.sh 2> /dev/null && base=$(resolve_base 2> /dev/null); then
+      name=
+      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)" = "$base" ] || continue
+        name=$(git rev-parse --abbrev-ref "$ref" 2> /dev/null || echo "$ref")
+        break
+      done
+      ahead=$(git rev-list --count "$base..HEAD" 2> /dev/null)
+      if [ -n "$name" ] && [ -n "$ahead" ]; then
+        line="$line; base $name at $(git rev-parse --short "$base"), $ahead commits ahead"
+      elif [ -z "$name" ]; then
+        line="$line; no base branch (origin/HEAD, origin/main, main): only uncommitted changes count"
+      fi
+    fi
+    lines+=("$line")
+  fi
+  if st=$(git status --porcelain --untracked-files=all 2> /dev/null); then
+    untracked=$(printf '%s\n' "$st" | grep -c '^??')
+    changed=$(printf '%s\n' "$st" | grep -v '^??' | grep -c .)
+    lines+=("uncommitted files: $changed; untracked files: $untracked")
+  fi
+  conflicts=$(git ls-files -u 2> /dev/null | cut -f2 | sort -u | grep -c .)
+  [ "${conflicts:-0}" -gt 0 ] &&
+    lines+=("unresolved merge conflicts in $conflicts files: resolve them first (docs/contributing.md, section 5)")
+fi
+
+shopt -s nullglob
+plans=()
+for p in docs/plans/*.md; do
+  [ "$(basename "$p")" = README.md ] || plans+=("$p")
+done
+# SESSION_START_TODAY (YYYY-MM-DD) stands in for the clock, for the tests.
+today=${SESSION_START_TODAY:-$(date +%Y-%m-%d)}
+# Plans past their review-by come first, then those without one, then the rest, so the five shown
+# never hide a past one; the line for the rest counts the past ones among them.
+past=() undated=() ahead=()
+for p in ${plans[@]+"${plans[@]}"}; do
+  rb=$(awk 'NR == 1 && $0 != "---" {exit} NR > 1 && $0 == "---" {exit}
+    /^review-by:/ {sub(/^review-by:[[:space:]]*/, ""); gsub(/["'\''[:space:]]/, ""); print; exit}' "$p" 2> /dev/null)
+  if ! printf '%s' "$rb" | grep -q -E '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'; then
+    undated+=("plan $p: no review-by date")
+  elif [[ "$rb" < "$today" ]]; then
+    past+=("plan $p: review-by $rb is past; update or delete it (docs/documentation-rules.md, section 5)")
+  else
+    ahead+=("plan $p: review-by $rb")
+  fi
+done
+ordered=(${past[@]+"${past[@]}"} ${undated[@]+"${undated[@]}"} ${ahead[@]+"${ahead[@]}"})
+[ "${#ordered[@]}" -eq 0 ] || for i in "${!ordered[@]}"; do
+  if [ "$i" -eq 5 ]; then
+    rest="and $(( ${#ordered[@]} - 5 )) more plans in docs/plans/"
+    [ "${#past[@]}" -le 5 ] || rest="$rest, $(( ${#past[@]} - 5 )) of them past their review-by"
+    lines+=("$rest")
+    break
+  fi
+  lines+=("${ordered[$i]}")
+done
+
+[ "${#lines[@]}" -gt 0 ] || exit 0
+echo "Local state at session start (.claude/hooks/session-start.sh):"
+printf -- '- %s\n' "${lines[@]}"
+exit 0

package/template/.claude/hooks/stop-check-decisions.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Stop hook: Claude Code may not finish a turn while the decision-record integrity checks of
+# scripts/check-decisions.sh fail (docs/documentation-rules.md, sections 5 and 7). Merge readiness
+# is not checked here: an agent legitimately stops with a `proposed` record to ask the owner. Exit 2
+# sends the agent back with the check output. DOCS_GUARD=off disables it, as for the protect hook
+# (docs/documentation-rules.md, section 8).
+set -uo pipefail
+[ "${DOCS_GUARD:-on}" = "off" ] && exit 0
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+# During an unresolved merge conflict (a template update) the checks cannot pass yet; let the
+# agent stop and ask instead of looping.
+if [ -n "$(git ls-files -u 2>/dev/null)" ]; then
+  echo "Unresolved merge conflicts: checks resume once they are resolved (docs/contributing.md, section 5)." >&2
+  exit 0
+fi
+RALPH_SESSION=$(node scripts/lib/json.mjs get session_id none 2>/dev/null || echo none)
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh 2>/dev/null || { ralph_block() { printf '%s\n' "$2" >&2; exit 2; }; ralph_pass() { :; }; }
+if out=$(scripts/check-decisions.sh 2>&1); then
+  ralph_pass decisions
+  exit 0
+fi
+ralph_block decisions "$(printf 'Decision record checks failed; fix them before finishing (docs/documentation-rules.md, section 5):\n%s' "$out")"

package/template/.claude/hooks/stop-check-docs.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Stop hook: Claude Code may not finish a turn while the documentation checks fail. Runs
+# scripts/check-docs.sh only when a Markdown file differs from the base of the change
+# (scripts/lib/git-base.sh), committed or not, so unrelated turns pay nothing. Exit 2 sends the
+# agent back with the check output; a missing tool is reported without blocking.
+set -uo pipefail
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+# During an unresolved merge conflict (a template update) the checks cannot pass yet; let the
+# agent stop and ask instead of looping.
+if [ -n "$(git ls-files -u 2>/dev/null)" ]; then
+  echo "Unresolved merge conflicts: checks resume once they are resolved (docs/contributing.md, section 5)." >&2
+  exit 0
+fi
+# shellcheck source=scripts/lib/git-base.sh
+. scripts/lib/git-base.sh
+base=$(resolve_base 2>/dev/null) || exit 0
+changed=$( { git diff --name-only "$base" -- '*.md'; git ls-files --others --exclude-standard -- '*.md'; } 2>/dev/null | head -n 1)
+[ -n "$changed" ] || exit 0
+RALPH_SESSION=$(node scripts/lib/json.mjs get session_id none 2>/dev/null || echo none)
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh 2>/dev/null || { ralph_block() { printf '%s\n' "$2" >&2; exit 2; }; ralph_pass() { :; }; }
+out=$(scripts/check-docs.sh 2>&1)
+case $? in
+  0) ralph_pass docs; exit 0 ;;
+  3) printf 'Documentation checks could not run; install the missing tool:\n%s\n' "$out" >&2; exit 1 ;;
+esac
+ralph_block docs "$(printf 'Documentation checks failed; fix them before finishing (AGENTS.md, section 6):\n%s' "$out")"

package/template/.claude/hooks/stop-check-fast.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Stop hook: Claude Code may not finish a turn while the project's fast check fails
+# (docs/documentation-rules.md, section 7). Runs `scripts/env.sh fast`, the CHECK_FAST command of
+# .claude/harness.conf, only when a file other than Markdown differs from the base of the change
+# (scripts/lib/git-base.sh), committed or not, untracked included. It skips when CHECK_FAST is
+# empty or is the default scripts/check-docs.sh, which stop-check-docs.sh already runs for
+# Markdown. Exit 2 sends the agent back with the command's output, up to the Ralph cap.
+set -uo pipefail
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+# During an unresolved merge conflict (a template update) the checks cannot pass yet; let the
+# agent stop and ask instead of looping.
+if [ -n "$(git ls-files -u 2>/dev/null)" ]; then
+  echo "Unresolved merge conflicts: checks resume once they are resolved (docs/contributing.md, section 5)." >&2
+  exit 0
+fi
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh 2>/dev/null || exit 0
+case "$(conf_get CHECK_FAST)" in
+  ''|scripts/check-docs.sh) exit 0 ;;
+esac
+# shellcheck source=scripts/lib/git-base.sh
+. scripts/lib/git-base.sh
+base=$(resolve_base 2>/dev/null) || exit 0
+changed=$( { git diff --name-only "$base" -- . ':(exclude)*.md'; git ls-files --others --exclude-standard -- . ':(exclude)*.md'; } 2>/dev/null | head -n 1)
+[ -n "$changed" ] || exit 0
+RALPH_SESSION=$(node scripts/lib/json.mjs get session_id none 2>/dev/null || echo none)
+if out=$(scripts/env.sh fast 2>&1); then
+  ralph_pass fast
+  exit 0
+fi
+ralph_block fast "$(printf 'The fast check (CHECK_FAST in .claude/harness.conf) failed; fix it before finishing (AGENTS.md, section 6):\n%s' "$(printf '%s\n' "$out" | tail -n 60)")"

package/template/.claude/hooks/stop-check-template.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Stop hook: Claude Code may not finish a turn while a template-owned file differs from the template
+# or AGENTS.md lost its project block (docs/documentation-rules.md, section 9). Exit 2 sends the
+# agent back with the check output. DOCS_GUARD=off disables it, as for the protect hook.
+set -uo pipefail
+[ "${DOCS_GUARD:-on}" = "off" ] && exit 0
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+# During an unresolved merge conflict (a template update) the checks cannot pass yet; let the
+# agent stop and ask instead of looping.
+if [ -n "$(git ls-files -u 2>/dev/null)" ]; then
+  echo "Unresolved merge conflicts: checks resume once they are resolved (docs/contributing.md, section 5)." >&2
+  exit 0
+fi
+RALPH_SESSION=$(node scripts/lib/json.mjs get session_id none 2>/dev/null || echo none)
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh 2>/dev/null || { ralph_block() { printf '%s\n' "$2" >&2; exit 2; }; ralph_pass() { :; }; }
+if out=$(scripts/check-template.sh 2>&1); then
+  ralph_pass template
+  exit 0
+fi
+ralph_block template "$(printf 'Template checks failed; restore the template-owned files before finishing (docs/documentation-rules.md, section 9):\n%s' "$out")"

package/template/.claude/hooks/stop-run-project-hooks.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Stop hook: runs the project's own Stop hooks, .claude/hooks/project/stop/*.sh in name order, with
+# the same input (docs/documentation-rules.md, section 9). A project hook blocks the agent by
+# exiting with 2; its output goes to the agent. A hook that is not executable blocks too, because
+# a silent gate is worse than a loud one. Other exit codes are reported without blocking.
+set -uo pipefail
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+shopt -s nullglob
+input=$(cat)
+RALPH_SESSION=$(printf '%s' "$input" | node scripts/lib/json.mjs get session_id none 2>/dev/null || echo none)
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh 2>/dev/null || { ralph_block() { printf '%s\n' "$2" >&2; exit 2; }; ralph_pass() { :; }; }
+for h in "$root"/.claude/hooks/project/stop/*.sh; do
+  if [ ! -x "$h" ]; then
+    printf 'Project Stop hook %s is not executable; run chmod +x and commit it.\n' "$h" >&2
+    exit 2
+  fi
+  out=$(printf '%s' "$input" | "$h" 2>&1)
+  code=$?
+  [ "$code" -eq 2 ] && ralph_block "project-$(basename "$h" .sh)" "$out"
+  [ -z "$out" ] || printf '%s\n' "$out" >&2
+  ralph_pass "project-$(basename "$h" .sh)"
+  [ "$code" -eq 0 ] || printf 'Project Stop hook %s exited with %s\n' "$h" "$code" >&2
+done
+exit 0

package/template/.claude/path-classes

@@ -0,0 +1,102 @@
+# Path classes of this project (docs/documentation-rules.md, sections 8 and 9): one
+# "<class> <glob>" per line, a shell glob relative to the repository root, in which * also matches
+# /. A path takes the highest class among the lines that match it and the template's built-in
+# ones (approval for the rules, the map, ADRs on main, and the generated manifest, answers file,
+# and settings). A path that nothing
+# matches is low when it is Markdown, otherwise normal. This file belongs to the project; a
+# change to it is class approval.
+#   approval  the owner approves the edit first: the protect hook asks, a headless run is denied
+#   high      with the dual_review module, the Santa loop before the pull request
+#   gate      listed under "Gate files" in the pull request, reviewed by the owner after the merge
+#   normal    with the dual_review module, one reviewer before the pull request
+#   low       no reviewer before the pull request
+
+# Secrets and tools with irreversible effects.
+approval .env
+approval .env.*
+approval *.pem
+approval *.key
+
+# Security, access, data migrations, money, public contracts. Add the project's own, such as
+# policy or limits.
+high *auth/*
+high *security/*
+high *secrets/*
+high *migrations/*
+high *billing/*
+high *payments/*
+high contracts/*
+
+# Gates: workflows, the project's checks and Stop hooks, and the harness settings.
+gate .github/workflows/*
+gate scripts/checks.d/*
+gate .claude/hooks/project/*
+gate .claude/harness.conf
+
+# Gates of any stack: dependency updates, pre-commit hooks, task runners, and tool versions. The
+# `*/` lines gate the files of Make, just, and Task in subdirectories too, and `*.mk` every file
+# with that extension; tool versions and mise are gated at the root only.
+gate .github/dependabot.y*ml
+gate renovate.json*
+gate .github/renovate.json*
+gate .renovaterc*
+gate .pre-commit-config.yaml
+gate Makefile
+gate */Makefile
+gate makefile
+gate */makefile
+gate GNUmakefile
+gate */GNUmakefile
+gate *.mk
+gate justfile
+gate */justfile
+gate Justfile
+gate */Justfile
+gate .justfile
+gate */.justfile
+gate Taskfile.y*ml
+gate */Taskfile.y*ml
+gate Taskfile.dist.y*ml
+gate */Taskfile.dist.y*ml
+gate taskfile.y*ml
+gate */taskfile.y*ml
+gate taskfile.dist.y*ml
+gate */taskfile.dist.y*ml
+gate .tool-versions
+gate mise.toml
+gate mise.*.toml
+gate .mise.toml
+gate .mise.*.toml
+gate mise/config.toml
+gate .mise/config.toml
+gate .config/mise.toml
+gate .config/mise/*
+
+# Dependency manifests and lock files, and the configuration of linters, test runners, coverage,
+# and mutation testing.
+gate package.json
+gate */package.json
+gate package-lock.json
+gate pnpm-lock.yaml
+gate yarn.lock
+gate pyproject.toml
+gate uv.lock
+gate poetry.lock
+gate requirements*.txt
+gate go.mod
+gate go.sum
+gate Cargo.toml
+gate Cargo.lock
+gate .eslintrc*
+gate eslint.config.*
+gate .prettierrc*
+gate ruff.toml
+gate .ruff.toml
+gate pytest.ini
+gate tox.ini
+gate .coveragerc
+gate jest.config.*
+gate vitest.config.*
+gate tsconfig*.json
+gate stryker.conf.*
+gate .golangci.yml

package/template/.claude/settings.project.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "deny": []
+  }
+}