create-afe-project 0.0.0-stage → 1.0.0

package/template/scripts/check-decisions.sh

@@ -0,0 +1,382 @@
+#!/usr/bin/env bash
+# Decision-record and merge-readiness checks (docs/documentation-rules.md, sections 5, 7, and 8),
+# run by scripts/check.sh. The Stop hook .claude/hooks/stop-check-decisions.sh runs the integrity
+# checks; the `decisions` workflow (.github/workflows/decisions.yml) runs both kinds on every pull
+# request. The integrity checks also require `scope`, `summary`, and the next free number in new
+# records, and a fresh index. Merge readiness reads the pull request description: the labels of
+# its open items, "Acceptance and test plan", "Owner decisions" for every marker the change adds,
+# "Gate files" for every gate path it touches, and the "Metrics" tables (docs/contributing.md,
+# section 3); with the acceptance_check module it runs scripts/check-acceptance.sh too.
+#
+# Usage: scripts/check-decisions.sh [--base <ref>] [--ready [--pr-body <file>] | --classes]
+#   --base     the branch the change goes into; by default scripts/lib/git-base.sh chooses it.
+#              The change is everything between the merge base and the working tree, untracked
+#              files included. An unknown ref is an error.
+#   --ready    run the merge-readiness checks instead of the integrity checks.
+#   --pr-body  the pull request description to check (docs/contributing.md, section 3).
+#   --classes  print "<class><TAB><path>" for every path the change touches, then the review it
+#              needs before the pull request: "review<TAB>none|one|santa" (documentation-rules.md,
+#              section 8), and nothing else.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+base= ready=0 body= classes=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base) base="${2:?--base needs a ref}"; shift 2 ;;
+    --ready) ready=1; shift ;;
+    --classes) classes=1; shift ;;
+    --pr-body) body="${2:?--pr-body needs a file}"; shift 2 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+failures=0
+fail() { printf 'FAIL: %s\n' "$*"; failures=$((failures + 1)); }
+skip() { printf 'SKIP: %s\n' "$*"; }
+
+# shellcheck source=scripts/lib/git-base.sh
+. scripts/lib/git-base.sh
+# shellcheck source=scripts/lib/classes.sh
+. scripts/lib/classes.sh
+# shellcheck source=scripts/lib/harness-conf.sh
+. scripts/lib/harness-conf.sh
+mb=$(resolve_base "$base") || exit 2
+base="${base:-the default base}"
+
+# Every path the change touches: changed against the merge base, deleted, or untracked.
+changed_paths() {
+  { git diff --name-only --no-renames "$mb"; git ls-files --others --exclude-standard; } | sort -u
+}
+
+if [ "$classes" -eq 1 ]; then
+  paths=()
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    paths+=("$p")
+    printf '%s\t%s\n' "$(class_of "$p" "$mb")" "$p"
+  done < <(changed_paths)
+  printf 'review\t%s\n' "$(review_level "$mb" ${paths[@]+"${paths[@]}"})"
+  exit 0
+fi
+
+# Prints the front-matter status of the record read from stdin.
+status_of() {
+  tr -d '\r' | awk 'NR==1 && $0!="---" {exit} NR>1 && $0=="---" {exit}
+       NR>1 && /^status:/ {sub(/^status:[[:space:]]*/, ""); sub(/[[:space:]]+$/, ""); gsub(/^["\047]|["\047]$/, ""); print; exit}'
+}
+
+# True when the front matter of the record read from stdin has a non-empty field $1.
+has_field() {
+  tr -d '\r' | awk -v k="$1" 'NR==1 && $0!="---" {exit 1} NR>1 && $0=="---" {exit 1}
+       NR>1 && index($0, k ":")==1 {v = substr($0, length(k) + 2); gsub(/[[:space:]"\047]/, "", v)
+         done = 1; exit (v == "" || v == "[]")}
+       END {if (!done) exit 1}'
+}
+
+# Prints the record read from stdin without its front-matter status line.
+without_status() {
+  awk 'NR==1 && $0=="---" {fm=1; print; next}
+       fm && $0=="---" {fm=0}
+       !(fm && /^status:/) {print}'
+}
+
+is_record() {
+  case "$1" in docs/decisions/[0-9][0-9][0-9][0-9]-*.md) return 0 ;; esac
+  return 1
+}
+
+# Changed decision records as "<status letter><TAB><path>[<TAB><new path>]"; untracked files
+# count as added. The template and other files in docs/decisions/ are the protect hook's concern.
+changes=$( {
+  git diff --name-status -M "$mb" -- docs/decisions/
+  git ls-files --others --exclude-standard -- docs/decisions/ | awk '{print "A\t" $0}'
+} )
+added=()
+while IFS=$'\t' read -r st p1 p2; do
+  [ -n "$st" ] || continue
+  case "$st" in
+    A) is_record "$p1" && added+=("$p1") ;;
+    C*) is_record "$p2" && added+=("$p2") ;;
+  esac
+done <<< "$changes"
+
+# True when the record numbered $1 is added by the change.
+added_number() {
+  local p
+  for p in ${added[@]+"${added[@]}"}; do
+    case "$p" in "docs/decisions/$1-"*) return 0 ;; esac
+  done
+  return 1
+}
+
+check_added() {
+  local p="$1" status num
+  status=$(status_of < "$p")
+  case "$status" in
+    proposed|accepted|rejected) ;;
+    *) fail "$p: a new record starts as 'proposed', 'accepted', or 'rejected', got '${status:-none}'" ;;
+  esac
+  has_field scope < "$p" || fail "$p: front matter has no 'scope' (adr-template.md)"
+  has_field summary < "$p" || fail "$p: front matter has no 'summary' (adr-template.md)"
+  num=$(basename "$p" | cut -c1-4)
+  set -- docs/decisions/"$num"-*.md
+  [ "$#" -eq 1 ] || fail "$p: number $num is used by $# records"
+  # A new record takes the highest number on the base branch plus one, counting the records
+  # added before it in this change (documentation-rules.md, section 5).
+  local max next
+  max=$(git ls-tree --name-only "$mb" docs/decisions/ | sed -n 's#^docs/decisions/\([0-9]\{4\}\)-.*#\1#p' | sort | tail -n 1)
+  next=$(printf '%04d' $((10#${max:-0} + 1)))
+  for q in $(printf '%s\n' ${added[@]+"${added[@]}"} | sort); do
+    [ "$q" = "$p" ] && break
+    next=$(printf '%04d' $((10#$next + 1)))
+  done
+  [ "$num" = "$next" ] || fail "$p: a new record takes number $next (highest existing plus one), got $num"
+}
+
+check_modified() {
+  local p="$1" old new os ns
+  old=$(git show "$mb:$p")
+  new=$(cat "$p")
+  if [ "$(printf '%s\n' "$old" | without_status)" != "$(printf '%s\n' "$new" | without_status)" ]; then
+    fail "$p: exists on $base and changed beyond its status line; reject it and add a new record instead (documentation-rules.md, section 5)"
+  fi
+  os=$(printf '%s\n' "$old" | status_of)
+  ns=$(printf '%s\n' "$new" | status_of)
+  case "$os -> $ns" in
+    "proposed -> accepted"|"proposed -> rejected"|"accepted -> deprecated") ;;
+    "accepted -> superseded by ADR-"[0-9][0-9][0-9][0-9])
+      added_number "${ns##*ADR-}" ||
+        fail "$p: superseded by ${ns##* }, which this change does not add" ;;
+    *) fail "$p: status '$os' -> '$ns' is not a transition of documentation-rules.md, section 3" ;;
+  esac
+}
+
+# A pull request description, file $1: every item under "Assumptions and open questions" is
+# "None" or carries one of the labels of docs/contributing.md, section 3.
+check_body() {
+  local section items=0 line item doc
+  section=$(tr -d '\r' < "$1" | awk '/^## /{in_s = ($0 ~ /^## Assumptions and open questions[[:space:]]*$/); seen = seen || in_s; next}
+                                    in_s {print} END {exit !seen}') || {
+    fail "pull request description: no '## Assumptions and open questions' section"
+    return
+  }
+  while IFS= read -r line; do
+    indented=0
+    case "$line" in [[:space:]]*) indented=1 ;; esac
+    line="${line#"${line%%[![:space:]]*}"}"
+    case "$line" in
+      None|None.) items=$((items + 1)); continue ;;
+      "- "*|"* "*|"+ "*) item="${line#??}" ;;
+      [0-9]". "*|[0-9][0-9]". "*) item="${line#*. }" ;;
+      *) continue ;;
+    esac
+    # Labels are written as label: or `label:` or `label`:.
+    item=$(printf '%s' "$item" | sed -E 's/^`([a-z]+):?`:?/\1:/')
+    # An indented bullet without a label is a detail of the item above it.
+    if [ "$indented" = 1 ]; then
+      case "$item" in blocking:*|recorded:*|assumption:*|limit:*) ;; *) continue ;; esac
+    fi
+    items=$((items + 1))
+    case "$item" in
+      None|None.|assumption:*|limit:*) ;;
+      blocking:*) fail "blocking item still open: ${item:0:100}" ;;
+      recorded:*)
+        doc=$(printf '%s' "$item" | grep -o -E 'docs/[A-Za-z0-9_./-]+\.md' | head -n 1)
+        if [ -z "$doc" ]; then
+          fail "recorded item names no owner document (docs/...md): ${item:0:100}"
+        elif [ ! -f "$doc" ]; then
+          fail "recorded item names $doc, which does not exist"
+        fi ;;
+      *) fail "item labelled neither 'blocking:', 'recorded:', 'assumption:', nor 'limit:': ${item:0:100}" ;;
+    esac
+  done <<< "$section"
+  [ "$items" -gt 0 ] || fail "pull request description: 'Assumptions and open questions' is empty; write 'None'"
+}
+
+# Prints the lines of section "## $1" of the description $2; fails when it has no such section.
+section_of() {
+  tr -d '\r' < "$2" | awk -v h="## $1" '/^## / {l = $0; sub(/[[:space:]]+$/, "", l); s = (l == h); seen = seen || s; next}
+                                        s {print} END {exit !seen}'
+}
+
+# Prints each top-level item of the section read from stdin on one line: a bullet or a numbered
+# item with its continuation lines, or a bare "None".
+items() {
+  awk '/^([-*+]|[0-9]+\.) / {if (it != "") print it; it = $0; sub(/^([-*+]|[0-9]+\.) +/, "", it); next}
+       /^[[:space:]]*$/ {next}
+       {l = $0; sub(/^[[:space:]]+/, "", l); if (it != "") it = it " " l; else print l}
+       END {if (it != "") print it}'
+}
+
+# "Acceptance and test plan": each item is "None" with its reason, or names at least one file in
+# backticks, and every path in backticks exists in the working tree. A path is a backticked token
+# without spaces that has a "/" or ends in a file extension that starts with a letter (`test_x.py`,
+# not `v1.2.0`); a "#anchor", a "::test" suffix, or a ":line" suffix is ignored.
+check_acceptance() {
+  local sec item paths p n=0
+  sec=$(section_of "Acceptance and test plan" "$1") || {
+    fail "pull request description: no '## Acceptance and test plan' section (docs/contributing.md, section 3)"
+    return
+  }
+  while IFS= read -r item; do
+    n=$((n + 1))
+    case "$item" in
+      None:*|'None ('*|'None -'*|'None, '*) continue ;;
+      None|None.) fail "Acceptance: 'None' needs its reason, such as 'None: documentation only'"; continue ;;
+    esac
+    paths=$(printf '%s\n' "$item" | grep -o '`[^`]*`' | tr -d '`' | sed -E 's/(::|#).*$//; s/:[0-9]+$//' |
+      grep -E '^([A-Za-z0-9_.@+-]+(/[A-Za-z0-9_.@+-]+)+|[A-Za-z0-9_@+-][A-Za-z0-9_.@+-]*\.[A-Za-z][A-Za-z0-9]*)$')
+    if [ -z "$paths" ]; then
+      fail "Acceptance item names no test file in backticks: ${item:0:100}"
+      continue
+    fi
+    while IFS= read -r p; do
+      [ -e "$p" ] || fail "Acceptance names $p, which does not exist"
+    done <<< "$paths"
+  done < <(printf '%s\n' "$sec" | items)
+  [ "$n" -gt 0 ] || fail "pull request description: 'Acceptance' is empty; write 'None' with the reason"
+}
+
+# Prints the rows of the Markdown tables read from stdin, one per line: the number of cells, then
+# the cells, trimmed, separated by tabs. A row starts and ends with "|".
+table_rows() {
+  awk -F'|' '/^[[:space:]]*\|/ {n = 0; out = ""
+    for (i = 2; i < NF; i++) {c = $i; gsub(/^[ \t]+|[ \t]+$/, "", c); out = out "\t" c; n++}
+    print n out}'
+}
+
+# "Metrics": the two tables of docs/contributing.md, section 3. A sensor row has six cells: the
+# sensor, the class (blocker or suggestion), and the numbers found, fixed, limit, and declined,
+# which add up; a blocker is never a limit. The measure table has each measure once: First
+# check.sh (pass or fail); Ralph iterations, Santa rounds, Owner interventions, and Files outside
+# the scope, each a number, optionally followed by details; and Regression of (none, or the #N of
+# the pull request whose behaviour the change repairs).
+check_metrics() {
+  local sec n a b c d e f m measures=
+  sec=$(section_of Metrics "$1") || {
+    fail "pull request description: no '## Metrics' section (docs/contributing.md, section 3)"
+    return
+  }
+  while IFS=$'\t' read -r n a b c d e f; do
+    case "$a" in Sensor|Measure|''|:-*|-*) continue ;; esac
+    if [ "$n" = 6 ]; then
+      case "$b" in blocker|suggestion) ;; *) fail "Metrics: $a: class '$b' is neither blocker nor suggestion"; continue ;; esac
+      for m in "$c" "$d" "$e" "$f"; do
+        case "$m" in ''|*[!0-9]*) fail "Metrics: $a $b: '$m' is not a number"; continue 2 ;; esac
+      done
+      [ "$c" -eq $((d + e + f)) ] ||
+        fail "Metrics: $a counts $c $b findings and answers $((d + e + f)); each finding is answered once"
+      [ "$b" != blocker ] || [ "$e" -eq 0 ] || fail "Metrics: $a: a blocker is fixed or declined, never a limit"
+    elif [ "$n" = 2 ]; then
+      case "$a:$b" in
+        'First check.sh:pass'*|'First check.sh:fail'*) ;;
+        'Ralph iterations:'[0-9]*|'Santa rounds:'[0-9]*|'Owner interventions:'[0-9]*|'Files outside the scope:'[0-9]*) ;;
+        'Regression of:none'*|'Regression of:#'[0-9]*) ;;
+        *) fail "Metrics: measure '$a' with value '$b' is outside the forms of docs/contributing.md, section 3"; continue ;;
+      esac
+      case "$measures|" in *"|$a|"*) fail "Metrics: measure '$a' appears twice" ;; esac
+      measures="$measures|$a"
+    else
+      fail "Metrics: a table row with $n cells; sensor rows have 6, measure rows 2"
+    fi
+  done < <(printf '%s\n' "$sec" | table_rows)
+  for m in 'First check.sh' 'Ralph iterations' 'Santa rounds' 'Owner interventions' 'Files outside the scope' 'Regression of'; do
+    case "$measures|" in *"|$m|"*) ;; *) fail "Metrics: no '$m' row" ;; esac
+  done
+}
+
+# Prints the path of the Markdown file of every `Decided by the owner, YYYY-MM-DD` marker the
+# change adds, once per marker: added lines of the diff against the merge base, and untracked
+# files. Markers live in owner documents, so other files, such as tests, are not read.
+added_markers() {
+  local re='Decided by the owner, [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]' f n
+  git diff --no-renames -U0 "$mb" -- '*.md' | awk -v re="$re" '/^\+\+\+ / {p = $2; sub(/^b\//, "", p); next}
+    /^\+/ && p != "/dev/null" {n = gsub(re, "&"); for (i = 0; i < n; i++) print p}'
+  while IFS= read -r -d '' f; do
+    n=$(grep -o -E "$re" "$f" 2>/dev/null | wc -l | tr -d ' ')
+    while [ "${n:-0}" -gt 0 ]; do printf '%s\n' "$f"; n=$((n - 1)); done
+  done < <(git ls-files -z --others --exclude-standard -- '*.md')
+}
+
+# "Owner decisions": each file names as many items as the markers the change adds to it.
+check_markers() {
+  local markers sec need f have
+  markers=$(added_markers | sort | uniq -c)
+  [ -n "$markers" ] || return 0
+  sec=$(section_of "Owner decisions" "$1") || sec=
+  while read -r need f; do
+    have=$(printf '%s\n' "$sec" | items | grep -c -F -- "$f")
+    [ "$have" -ge "$need" ] ||
+      fail "$f: the change adds $need 'Decided by the owner' marker(s) and 'Owner decisions' names the file in $have item(s) (docs/contributing.md, section 3)"
+  done <<< "$markers"
+}
+
+# A small diff (docs/contributing.md, section 1): a warning, never a failure, when the lines the
+# change adds and deletes, generated files left out, exceed DIFF_WARN_LINES of .claude/harness.conf.
+check_size() {
+  local limit n
+  limit=$(conf_get DIFF_WARN_LINES)
+  [ -n "$limit" ] || return 0
+  n=$(git diff --numstat "$mb" -- . ':(exclude).template/owned.sha256' ':(exclude).afe-answers.json' \
+        ':(exclude).copier-answers.yml' ':(exclude).claude/settings.json' ':(exclude)docs/decisions/README.md' | awk '{a += $1 + $2} END {print a + 0}')
+  n=$((n + $(git ls-files -z --others --exclude-standard | xargs -0 cat 2>/dev/null | wc -l | tr -d ' ')))
+  [ "$n" -le "$limit" ] || echo "WARNING: the change has $n changed lines, more than DIFF_WARN_LINES ($limit); split it, or say in the description why it is one change"
+}
+
+# "Gate files": names every path of class gate the change touches; prints them.
+check_gate_files() {
+  local sec p
+  sec=$(section_of "Gate files" "$1") || sec=
+  while IFS= read -r p; do
+    [ -n "$p" ] && [ "$(class_of "$p" "$mb")" = gate ] || continue
+    echo "class gate, reviewed after the merge: $p"
+    printf '%s\n' "$sec" | grep -q -F -- "$p" ||
+      fail "$p: class gate (documentation-rules.md, section 8); list it under 'Gate files'"
+  done < <(changed_paths)
+}
+
+if [ "$ready" -eq 0 ]; then
+  echo "== decision records: changes against $base"
+  [ -n "$changes" ] || skip "no decision record changed"
+  while IFS=$'\t' read -r st p1 p2; do
+    [ -n "$st" ] || continue
+    case "$st" in
+      A) is_record "$p1" && check_added "$p1" ;;
+      C*) is_record "$p2" && check_added "$p2" ;;
+      M|T) is_record "$p1" && check_modified "$p1" ;;
+      D) is_record "$p1" && fail "$p1: exists on $base and is deleted; records are never deleted, their status changes (documentation-rules.md, section 5)" ;;
+      R*) { is_record "$p1" || is_record "$p2"; } && fail "$p1: exists on $base and is renamed to $p2; records keep their file name" ;;
+    esac
+  done <<< "$changes"
+  echo "== decision index: docs/decisions/README.md matches the records"
+  scripts/gen-decisions-index.sh | cmp -s - docs/decisions/README.md ||
+    fail "docs/decisions/README.md is missing or stale; run scripts/gen-decisions-index.sh > docs/decisions/README.md"
+else
+  echo "== merge readiness: records added by the change"
+  [ "${#added[@]}" -gt 0 ] || skip "no decision record added"
+  for p in ${added[@]+"${added[@]}"}; do
+    [ "$(status_of < "$p")" = proposed ] &&
+      fail "$p: still 'proposed'; the owner accepts or rejects it before the merge (docs/contributing.md, section 3)"
+  done
+  echo "== merge readiness: pull request description"
+  if [ -n "$body" ]; then
+    check_body "$body"
+    check_acceptance "$body"
+    check_markers "$body"
+    check_gate_files "$body"
+    check_metrics "$body"
+    check_size
+    if [ -x scripts/check-acceptance.sh ]; then
+      scripts/check-acceptance.sh --pr-body "$body" || fail "scripts/check-acceptance.sh failed (above)"
+    fi
+  else
+    skip "no pull request description given (--pr-body)"
+  fi
+fi
+
+if [ "$failures" -gt 0 ]; then
+  echo "== decision checks failed: $failures"
+  exit 1
+fi
+echo "== decision checks passed (skipped checks listed above)"

package/template/scripts/check-docs.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Documentation checks, run by scripts/check.sh (AGENTS.md, section 6).
+# CI (.github/workflows/docs.yml) runs the same tools through their official actions
+# with the same configuration file, .markdownlint-cli2.jsonc, and the same link check.
+# Requires Node.js (node and npx).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# A missing tool is not a failed check: exit 3, which the Stop hook reports without blocking.
+for tool in node npx; do
+  command -v "$tool" >/dev/null || { echo "MISSING TOOL: $tool (see README.md, Checks)"; exit 3; }
+done
+
+echo "== markdownlint-cli2"
+npx --yes markdownlint-cli2@0.24.0
+
+echo "== links"
+node scripts/check-links.mjs
+
+echo "== documentation checks passed"

package/template/scripts/check-links.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// Internal link check of the Markdown files (docs/documentation-rules.md, section 7), with Node.js
+// only: every relative link and image points at an existing file or directory, and every #anchor
+// at a heading or an HTML id/name of the target Markdown file (the anchors GitHub generates).
+// External links (with a scheme, such as https: or mailto:) are not checked: the author verifies
+// them when adding them. Files ignored by Git are skipped; a file is read whole, so a link inside
+// a fenced code block or a code span is not a link.
+//
+// Usage: node scripts/check-links.mjs [file.md ...]   default: every Markdown file of the repository
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const root = process.cwd();
+
+function markdownFiles() {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '*.md'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\0').filter((f) => f && existsSync(f));
+  } catch {
+    const found = [];
+    const walk = (dir) => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.name === 'node_modules' || e.name === '.git') continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory()) walk(p);
+        else if (e.name.endsWith('.md')) found.push(relative(root, p));
+      }
+    };
+    walk(root);
+    return found;
+  }
+}
+
+// Blanks fenced code blocks, HTML comments, and code spans, keeping line numbers and offsets.
+function prose(text) {
+  const blank = (m) => m.replace(/[^\n]/g, ' ');
+  return text
+    .replace(/^( {0,3})(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^\1?\2[^\n]*$|(?![\s\S]))/gm, blank)
+    .replace(/<!--[\s\S]*?-->/g, blank)
+    .replace(/(`+)(?!`)[\s\S]*?[^`]\1(?!`)/g, blank);
+}
+
+// The anchor GitHub derives from a heading: lowercase, punctuation removed, spaces to hyphens.
+function slug(heading) {
+  const plain = heading
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .replace(/(^|\W)[*_]{1,3}|[*_]{1,3}(?=\W|$)/g, '$1')
+    .replace(/`/g, '');
+  return plain
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, '')
+    .replace(/ /g, '-');
+}
+
+const anchorCache = new Map();
+function anchors(file) {
+  if (anchorCache.has(file)) return anchorCache.get(file);
+  const text = readFileSync(file, 'utf8');
+  const lines = text.replace(/^( {0,3})(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^\1?\2[^\n]*$|(?![\s\S]))/gm, (m) => m.replace(/[^\n]/g, ' ')).split('\n');
+  const found = new Set();
+  const seen = new Map();
+  const add = (heading) => {
+    const base = slug(heading);
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    found.add(n ? `${base}-${n}` : base);
+  };
+  lines.forEach((line, i) => {
+    const atx = /^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/.exec(line);
+    if (atx) add(atx[1]);
+    else if (i > 0 && lines[i - 1].trim() && /^ {0,3}(=+|-+)[ \t]*$/.test(line) && !/^ {0,3}([-*_])( *\1){2,} *$/.test(lines[i - 1])) {
+      add(lines[i - 1].trim());
+    }
+    for (const m of line.matchAll(/<[a-z][^>]*\s(?:id|name)=["']([^"']+)["']/gi)) found.add(m[1]);
+  });
+  anchorCache.set(file, found);
+  return found;
+}
+
+function* links(text) {
+  const src = prose(text);
+  const lineOf = (i) => src.slice(0, i).split('\n').length;
+  // Inline links and images: [text](target "title"), with one level of nested brackets.
+  for (const m of src.matchAll(/!?\[(?:[^\[\]]|\[[^\]]*\])*\]\(\s*(<[^>]*>|[^\s)]*(?:\([^\s)]*\)[^\s)]*)*)(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g)) {
+    yield { target: m[1].replace(/^<|>$/g, ''), line: lineOf(m.index) };
+  }
+  // Reference definitions: [id]: target
+  for (const m of src.matchAll(/^ {0,3}\[[^\]]+\]:[ \t]*(<[^>]*>|\S+)/gm)) {
+    yield { target: m[1].replace(/^<|>$/g, ''), line: lineOf(m.index) };
+  }
+  // HTML links and images.
+  for (const m of src.matchAll(/<(?:a|img)\b[^>]*\s(?:href|src)=["']([^"']*)["']/gi)) {
+    yield { target: m[1], line: lineOf(m.index) };
+  }
+}
+
+function check(file) {
+  const problems = [];
+  for (const { target, line } of links(readFileSync(file, 'utf8'))) {
+    if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//')) continue;
+    const hash = target.indexOf('#');
+    const pathPart = (hash === -1 ? target : target.slice(0, hash)).replace(/\?.*$/, '');
+    const fragment = hash === -1 ? '' : target.slice(hash + 1);
+    let dest = file;
+    if (pathPart) {
+      let decoded;
+      try {
+        decoded = decodeURIComponent(pathPart);
+      } catch {
+        decoded = pathPart;
+      }
+      dest = decoded.startsWith('/') ? join(root, decoded) : resolve(dirname(file), decoded);
+      if (!existsSync(dest)) {
+        problems.push(`${file}:${line}: ${target}: no such file or directory`);
+        continue;
+      }
+    }
+    if (!fragment || !dest.endsWith('.md') || !statSync(dest).isFile()) continue;
+    let anchor;
+    try {
+      anchor = decodeURIComponent(fragment);
+    } catch {
+      anchor = fragment;
+    }
+    if (!anchors(dest).has(anchor) && !anchors(dest).has(anchor.toLowerCase())) {
+      problems.push(`${file}:${line}: ${target}: no heading or anchor #${anchor} in ${relative(root, dest) || file}`);
+    }
+  }
+  return problems;
+}
+
+const files = process.argv.length > 2 ? process.argv.slice(2) : markdownFiles();
+const problems = files.flatMap(check);
+for (const p of problems) console.log(`FAIL: ${p}`);
+console.log(`== links: ${files.length} Markdown files, ${problems.length} broken`);
+process.exit(problems.length ? 1 : 0);

package/template/scripts/check-project.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Project checks (docs/documentation-rules.md, section 9): runs every scripts/checks.d/*.sh in name
+# order. A project adds its own checks there; the template never writes to that directory.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+shopt -s nullglob
+
+checks=(scripts/checks.d/*.sh)
+if [ "${#checks[@]}" -eq 0 ]; then
+  echo "SKIP: no project checks in scripts/checks.d/"
+  exit 0
+fi
+failures=0
+for c in "${checks[@]}"; do
+  echo "== project check: $c"
+  if [ ! -x "$c" ]; then
+    echo "FAIL: $c is not executable"
+    failures=$((failures + 1))
+  elif ! "$c"; then
+    failures=$((failures + 1))
+  fi
+done
+if [ "$failures" -gt 0 ]; then
+  echo "== project checks failed: $failures"
+  exit 1
+fi
+echo "== project checks passed"

package/template/scripts/check-template.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Template integrity (docs/documentation-rules.md, sections 2 and 9): every template-owned file
+# listed in .template/owned.txt matches its hash in .template/owned.sha256, AGENTS.md contains
+# exactly one project block, the rule documents stay within their line budgets, and the generated
+# .claude/settings.json is current. The hash of AGENTS.md ignores the content of its project block.
+#
+# Usage: scripts/check-template.sh [--write]
+#   --write  record the current hashes; the template runs it after `create-afe-project` and
+#            `create-afe-project update`. Never run it to make a local edit of a template-owned file pass.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+list=.template/owned.txt
+manifest=.template/owned.sha256
+start='<!-- project:start -->'
+end='<!-- project:end -->'
+
+if command -v sha256sum >/dev/null; then sha() { sha256sum | cut -d' ' -f1; }
+else sha() { shasum -a 256 | cut -d' ' -f1; }; fi
+
+# Prints the content that the hash covers: AGENTS.md without the lines inside its project block.
+content() {
+  if [ "$1" = AGENTS.md ]; then
+    awk -v s="$start" -v e="$end" '$0==s {print; skip=1; next} $0==e {skip=0} !skip' "$1"
+  else
+    cat "$1"
+  fi
+}
+
+paths() { grep -v -E '^[[:space:]]*(#|$)' "$list"; }
+
+if [ "${1:-}" = "--write" ]; then
+  while IFS= read -r p; do
+    [ -f "$p" ] || { echo "FAIL: $p is listed in $list but missing" >&2; exit 1; }
+  done < <(paths)
+  paths | while IFS= read -r p; do printf '%s  %s\n' "$(content "$p" | sha)" "$p"; done > "$manifest"
+  echo "== template manifest written: $manifest"
+  exit 0
+fi
+
+failures=0
+fail() { printf 'FAIL: %s\n' "$*"; failures=$((failures + 1)); }
+
+echo "== template-owned files match $manifest"
+[ -f "$list" ] && [ -f "$manifest" ] || { echo "FAIL: $list or $manifest is missing"; exit 1; }
+while IFS= read -r p; do
+  if [ ! -f "$p" ]; then
+    fail "$p: template-owned file is missing"
+  elif [ "$(content "$p" | sha)" != "$(awk -v p="$p" '$2==p {print $1}' "$manifest")" ]; then
+    fail "$p: differs from the template; change it in the template repository and update (docs/contributing.md, section 5)"
+  fi
+done < <(paths)
+[ "$(paths | sort)" = "$(awk '{print $2}' "$manifest" | sort)" ] ||
+  fail "$manifest does not list exactly the paths of $list; it is regenerated only by a template update"
+
+echo "== AGENTS.md has exactly one project block"
+[ "$(grep -c -x -F "$start" AGENTS.md)" = 1 ] && [ "$(grep -c -x -F "$end" AGENTS.md)" = 1 ] &&
+  [ "$(grep -n -x -F "$start" AGENTS.md | cut -d: -f1)" -lt "$(grep -n -x -F "$end" AGENTS.md | cut -d: -f1)" ] ||
+  fail "AGENTS.md: expected one '$start' line followed by one '$end' line"
+
+echo "== AGENTS.md: template part at most 90 lines, project block at most 10 (documentation-rules.md, section 2)"
+block=$(awk -v s="$start" -v e="$end" '$0==s {f=1; next} $0==e {f=0} f' AGENTS.md | wc -l | tr -d ' ')
+total=$(wc -l < AGENTS.md | tr -d ' ')
+[ "$block" -le 10 ] || fail "AGENTS.md: the project block has $block lines; at most 10"
+[ $((total - block)) -le 90 ] || fail "AGENTS.md: the template part has $((total - block)) lines; at most 90 (a template defect)"
+
+echo "== rule documents within their line budgets (documentation-rules.md, section 2)"
+for spec in docs/documentation-rules.md:200 docs/contributing.md:200 docs/testing-rules.md:80; do
+  n=$(wc -l < "${spec%:*}" | tr -d ' ')
+  [ "$n" -le "${spec##*:}" ] || fail "${spec%:*}: $n lines; at most ${spec##*:} (a template defect)"
+done
+
+echo "== .claude/settings.json is generated from the template's and the project's settings"
+out=$(scripts/gen-settings.sh --check 2>&1) || fail "${out#FAIL: }"
+
+# Harness drift (docs/documentation-rules.md, section 7): a hook whose script is gone fails silently.
+echo "== every hook command of .claude/settings.json exists and is executable"
+while IFS= read -r hc; do
+  script=${hc%% *}; script=${script//\"/}; script=${script//\$CLAUDE_PROJECT_DIR/.}; script=${script//\$\{CLAUDE_PROJECT_DIR\}/.}
+  case "$script" in */*) [ -f "$script" ] && [ -x "$script" ] ||
+    fail ".claude/settings.json: the hook command $hc names $script, which is missing or not executable" ;; esac
+done < <(node scripts/lib/json.mjs hooks)
+
+if [ "$failures" -gt 0 ]; then
+  echo "== template checks failed: $failures"
+  exit 1
+fi
+echo "== template checks passed"