trae-coding-engine 0.1.0

package/templates/scripts/check-adr.sh

@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# Verify every ADR under docs/adr/ is in a terminal Status.
+# See docs/adr/CONVENTIONS.md.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/adr-meta.sh
+. scripts/lib/adr-meta.sh
+ADR_DIR="${ADR_DIR:-docs/adr}"
+
+# Grandfathered violations — historical ADRs that predate the convention.
+# Each entry MUST have a corresponding "现存待清理项" row in
+# docs/adr/CONVENTIONS.md so cleanup pressure is visible.
+GRANDFATHERED=()
+
+is_grandfathered() {
+  local f=$1
+  for g in "${GRANDFATHERED[@]+"${GRANDFATHERED[@]}"}"; do
+    [ "$f" = "$g" ] && return 0
+  done
+  return 1
+}
+
+# Intentionally-unused ADR numbers. Each entry needs a matching note in
+# docs/adr/CONVENTIONS.md (现存待清理项 / KNOWN_GAPS).
+KNOWN_GAPS=(0011)
+# Test override hook (space-separated). Empty string means "no gaps allowed".
+if [ "${KNOWN_GAPS_OVERRIDE+set}" = set ]; then
+  # shellcheck disable=SC2206
+  KNOWN_GAPS=(${KNOWN_GAPS_OVERRIDE})
+fi
+
+is_known_gap() {
+  local n=$1 g
+  for g in "${KNOWN_GAPS[@]+"${KNOWN_GAPS[@]}"}"; do
+    [ "$n" = "$g" ] && return 0
+  done
+  return 1
+}
+
+# Topic taxonomy comes from $ADR_TOPICS, defined once in scripts/lib/adr-meta.sh
+# (sourced above) so the linter and the index generator can't drift. The linter
+# validates **Topic** against this list, never against AGENTS.md §Skill Router
+# directly (the 7 path-skills are coarser). Topic→skill mapping is documented in
+# docs/adr/CONVENTIONS.md.
+
+VIOLATIONS=0
+WARNINGS=0
+# Back-citation enforcement mode: "warn" (Phase 2) or "hard" (Phase 3).
+BACKCITE_MODE="${BACKCITE_MODE:-hard}"
+GRANDFATHERED_HITS=0
+for f in "$ADR_DIR"/[0-9]*.md; do
+  [ -f "$f" ] || continue
+  status=$(awk '/^\*\*Status\*\*:/ { sub(/^\*\*Status\*\*:[[:space:]]*/, ""); print; exit }' "$f")
+
+  case "$status" in
+    Accepted|Deprecated|Withdrawn)
+      ;;
+    "Superseded by "*)
+      target="${status#Superseded by }"
+      if printf '%s' "$target" | grep -qE '^[0-9]{4}$'; then
+        if ! ls "$ADR_DIR/${target}-"*.md >/dev/null 2>&1; then
+          echo "  [VIOLATION]     $f — Superseded by $target but no $ADR_DIR/${target}-*.md exists"
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+      else
+        echo "  [VIOLATION]     $f — Superseded by '$target' is not a 4-digit ADR number (use 'Superseded by NNNN'; if no successor ADR, use Deprecated)"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+      ;;
+    Proposed)
+      if is_grandfathered "$f"; then
+        echo "  [GRANDFATHERED] $f — Status=Proposed (cleanup tracked in CONVENTIONS.md)"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        echo "  [VIOLATION]     $f — Status=Proposed not allowed on main; flip to Accepted before merging"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+      ;;
+    "")
+      if is_grandfathered "$f"; then
+        echo "  [GRANDFATHERED] $f — missing **Status** header (cleanup tracked in CONVENTIONS.md)"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        echo "  [VIOLATION]     $f — missing '**Status**:' header"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+      ;;
+    *)
+      echo "  [VIOLATION]     $f — unknown Status: '$status'"
+      VIOLATIONS=$((VIOLATIONS + 1))
+      ;;
+  esac
+done
+
+# Reference integrity: every ADR-NNNN / ADR NNNN token inside the ADR set must
+# resolve to an existing $ADR_DIR/NNNN-*.md. (Repo-wide scanning is intentionally
+# left to a future widening; ADR-internal cross-refs are the highest-value guard.)
+check_adr_refs() {
+  local f tok num
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    while IFS= read -r tok; do
+      num="$(printf '%s' "$tok" | grep -oE '[0-9]{4}')"
+      [ -z "$num" ] && continue
+      if ! ls "$ADR_DIR/${num}-"*.md >/dev/null 2>&1; then
+        echo "  [VIOLATION]     $f — references ${tok} but no $ADR_DIR/${num}-*.md exists"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    done < <(grep -oE 'ADR[- ][0-9]{4}' "$f" | sort -u)
+  done < <(adr_files)
+}
+check_adr_refs
+
+# Numbering: contiguous from the lowest present number to the highest; any
+# missing number must be allowlisted in KNOWN_GAPS.
+check_numbering() {
+  local nums max min n
+  nums="$(adr_files | while IFS= read -r f; do adr_num "$f"; done | sort -u)"
+  [ -z "$nums" ] && return 0
+  min="$(printf '%s\n' "$nums" | head -1)"
+  max="$(printf '%s\n' "$nums" | tail -1)"
+  for n in $(seq "$((10#$min))" "$((10#$max))"); do
+    local padded; padded="$(printf '%04d' "$n")"
+    if ! printf '%s\n' "$nums" | grep -qx "$padded"; then
+      if is_known_gap "$padded"; then
+        echo "  [KNOWN_GAP]     $padded — intentionally unused (tracked in CONVENTIONS.md)"
+      else
+        echo "  [VIOLATION]     missing ADR $padded — add the file or allowlist it in KNOWN_GAPS"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    fi
+  done
+}
+check_numbering
+
+check_topics() {
+  local f t ok w
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    t="$(adr_field "$f" Topic)"
+    if [ -z "$t" ]; then
+      echo "  [VIOLATION]     $f — missing '**Topic**:' header"
+      VIOLATIONS=$((VIOLATIONS + 1)); continue
+    fi
+    ok=0
+    for w in $ADR_TOPICS; do [ "$t" = "$w" ] && ok=1 && break; done
+    if [ "$ok" = 0 ]; then
+      echo "  [VIOLATION]     $f — Topic '$t' not in taxonomy ($ADR_TOPICS)"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done < <(adr_files)
+}
+check_topics
+
+# Keep the "valid topics" list in docs/adr/CONVENTIONS.md (the block between the
+# `adr-topics` markers) in EXACT set agreement with $ADR_TOPICS — both ways: a
+# topic in ADR_TOPICS but absent from the documented block, OR a documented topic
+# that is not a valid taxonomy value, is a violation. Only the marker block is
+# parsed (the Topic→skill routing table elsewhere uses the same backticked names
+# but must not count). Doc path is overridable for tests; default is the real one.
+check_topic_doc_sync() {
+  # Doc path is fixed in production; only a dedicated, clearly test-scoped var can
+  # repoint it (same discipline as ADR_TOPICS_TEST_OVERRIDE) — a stray env var
+  # must not be able to silently bypass this gate.
+  local conv="${ADR_CONV_DOC_TEST_OVERRIDE:-docs/adr/CONVENTIONS.md}" t
+  if [ ! -f "$conv" ]; then
+    echo "  [VIOLATION]     $conv — conventions doc not found; cannot verify taxonomy doc-sync"
+    VIOLATIONS=$((VIOLATIONS + 1)); return
+  fi
+  # Marker block must be well-formed first: exactly one start, exactly one end,
+  # end after start. Otherwise the awk extractor would run to EOF and harvest
+  # topics from outside the intended block (e.g. the routing table), letting a
+  # malformed/unclosed block pass doc-sync silently.
+  local n_start n_end l_start l_end
+  # `|| true`: grep -c exits 1 on zero matches, which under set -e would abort
+  # the script before we can report the malformed-block violation.
+  n_start="$(grep -c '<!-- adr-topics:start' "$conv" || true)"
+  n_end="$(grep -c '<!-- adr-topics:end' "$conv" || true)"
+  if [ "$n_start" != 1 ] || [ "$n_end" != 1 ]; then
+    echo "  [VIOLATION]     $conv — adr-topics marker block malformed (need exactly one start + one end; got start=$n_start end=$n_end)"
+    VIOLATIONS=$((VIOLATIONS + 1)); return
+  fi
+  l_start="$(grep -n '<!-- adr-topics:start' "$conv" | cut -d: -f1)"
+  l_end="$(grep -n '<!-- adr-topics:end' "$conv" | cut -d: -f1)"
+  if [ "$l_end" -le "$l_start" ]; then
+    echo "  [VIOLATION]     $conv — adr-topics:end must come after adr-topics:start"
+    VIOLATIONS=$((VIOLATIONS + 1)); return
+  fi
+  local doc_topics want
+  doc_topics="$(awk '
+    /<!-- adr-topics:start/ { on=1; next }
+    /<!-- adr-topics:end/   { on=0 }
+    on { while (match($0, /`[a-z0-9-]+`/)) { print substr($0, RSTART+1, RLENGTH-2); $0 = substr($0, RSTART+RLENGTH) } }
+  ' "$conv" | sort -u)"
+  if [ -z "$doc_topics" ]; then
+    echo "  [VIOLATION]     $conv — missing the adr-topics marker block; cannot verify taxonomy doc-sync"
+    VIOLATIONS=$((VIOLATIONS + 1)); return
+  fi
+  want="$(printf '%s\n' $ADR_TOPICS | sort -u)"
+  while IFS= read -r t; do
+    [ -z "$t" ] && continue
+    printf '%s\n' "$doc_topics" | grep -qx "$t" || {
+      echo "  [VIOLATION]     $conv — taxonomy topic '$t' (in ADR_TOPICS) is missing from the documented list"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    }
+  done <<< "$want"
+  while IFS= read -r t; do
+    [ -z "$t" ] && continue
+    printf '%s\n' "$want" | grep -qx "$t" || {
+      echo "  [VIOLATION]     $conv — documented topic '$t' is not a valid taxonomy value (not in ADR_TOPICS)"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    }
+  done <<< "$doc_topics"
+}
+check_topic_doc_sync
+
+# Back-citation: if A is "Superseded by B", B's body must cite A (its 4-digit
+# number). CONVENTIONS L51 requires it. Ships as WARN; flips to hard in Phase 3.
+check_back_citation() {
+  local f tgt a bfile cand
+  while IFS= read -r f; do
+    tgt="$(adr_supersede_target "$f")"
+    printf '%s' "$tgt" | grep -qE '^[0-9]{4}$' || continue
+    a="$(adr_num "$f")"
+    # Resolve the successor file via the same defensive-glob idiom as adr_files,
+    # NOT `ls ... | head` in a command substitution: under set -e + pipefail a
+    # missing target would make ls fail and abort the whole script before later
+    # checks and the summary run.
+    bfile=""
+    for cand in "$ADR_DIR/${tgt}-"*.md; do
+      [ -e "$cand" ] && { bfile="$cand"; break; }
+    done
+    [ -n "$bfile" ] || continue   # dangling target already caught by the supersede-target check
+    if grep -qE "(^|[^0-9])${a}([^0-9]|$)" "$bfile"; then
+      continue
+    fi
+    # Fail safe: only an explicit "warn" downgrades; any other value (including a
+    # typo'd BACKCITE_MODE) stays hard so enforcement is never silently lost.
+    if [ "$BACKCITE_MODE" = warn ]; then
+      echo "  [WARN]          $bfile — supersedes $a but never cites it (CONVENTIONS L51); backfill required"
+      WARNINGS=$((WARNINGS + 1))
+    else
+      echo "  [VIOLATION]     $bfile — supersedes $a but never cites it (CONVENTIONS L51)"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done < <(adr_files)
+}
+check_back_citation
+
+# Impl-drift hint: an Accepted ADR with no **Implementation** pointer may have
+# rotted or never shipped. WARN only — without a machine-readable **Code** glob
+# (deferred) we can only hint, and a hard gate on a heuristic trains people to
+# ignore the linter.
+check_impl_drift() {
+  local f s impl
+  while IFS= read -r f; do
+    s="$(adr_field "$f" Status)"
+    [ "$s" = Accepted ] || continue
+    impl="$(adr_field "$f" Implementation)"
+    if [ -z "$impl" ]; then
+      echo "  [WARN]          $f — Accepted but no **Implementation** pointer (possible drift)"
+      WARNINGS=$((WARNINGS + 1))
+    fi
+  done < <(adr_files)
+}
+check_impl_drift
+
+
+if [ $VIOLATIONS -eq 0 ]; then
+  if [ $GRANDFATHERED_HITS -gt 0 ]; then
+    echo "  [OK]  no new violations (${GRANDFATHERED_HITS} grandfathered awaiting cleanup)"
+  else
+    echo "  [OK]  all ADRs in terminal state"
+  fi
+  [ $WARNINGS -gt 0 ] && echo "  [NOTE] ${WARNINGS} warning(s) — see WARN lines above (non-blocking)"
+  exit 0
+fi
+
+echo
+echo "  ${VIOLATIONS} new violation(s). See docs/adr/CONVENTIONS.md."
+exit 1

package/templates/scripts/check-comment-i18n.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""check-comment-i18n: fail if CJK appears in genuine code comments.
+
+A COMMENT gate, not a whole-repo CJK gate. CJK inside string literals, raw
+strings (Go backticks), rune/char literals, URLs, or thrift annotation values
+is RUNTIME DATA and is explicitly OUT of scope — it must not be flagged.
+
+Inputs: newline-separated file paths on stdin (already filtered/excluded by
+the bash wrapper). Output: `path:line: <text>` per hit; exit 1 on any hit
+(plus a stderr summary), exit 0 otherwise.
+
+Pure python3 stdlib — no third-party imports.
+"""
+
+import json
+import re
+import sys
+
+# Ideographs (+Ext-A), kana, hangul, CJK/full-width punctuation.
+# Same ranges as the historical text-based gate.
+CJK = re.compile('[　-〿぀-ヿ㐀-䶿'
+                 '一-鿿가-힯＀-￯]')
+
+
+def _read_or_fail(path):
+    """Read a file as UTF-8, failing CLOSED on any OSError.
+
+    This is a gate: "cannot verify == do not pass". A swallowed read error
+    would let a file with CJK comments slip through silently, so emit a clear
+    stderr signal and exit non-zero instead of skipping the file.
+    """
+    try:
+        with open(path, encoding='utf-8', errors='replace') as f:
+            return f.read()
+    except OSError as e:
+        print(f'check-comment-i18n: ERROR: cannot read {path}: {e}',
+              file=sys.stderr)
+        sys.exit(2)
+
+
+def comment_hits(path, *, hash_line_comment, backtick_rawstring):
+    """Character-level state machine; return [(line, text)] for CJK comments.
+
+    States: code, line_comment, block_comment, string (``"`` or ``'``), and
+    (Go only) backtick_rawstring. Only text genuinely inside a comment is
+    checked for CJK. Block comments report the line where ``/*`` began.
+    """
+    out = []
+    data = _read_or_fail(path)
+
+    state = 'code'
+    i = 0
+    n = len(data)
+    line = 1
+    buf = []           # collected comment text
+    start_line = 0     # line where the current comment started
+    prefix = ''        # opener of the current line comment ('//' or '#')
+    string_end = ''    # closing delimiter of the open string literal
+
+    while i < n:
+        c = data[i]
+        nxt = data[i + 1] if i + 1 < n else ''
+
+        if state == 'code':
+            if c == '"' or c == "'":
+                state = 'string'
+                string_end = c
+            elif backtick_rawstring and c == '`':
+                state = 'backtick_rawstring'
+            elif c == '/' and nxt == '/':
+                state = 'line_comment'
+                buf = []
+                prefix = '//'
+                start_line = line
+                i += 2
+                continue
+            elif c == '/' and nxt == '*':
+                state = 'block_comment'
+                buf = []
+                start_line = line
+                i += 2
+                continue
+            elif hash_line_comment and c == '#':
+                state = 'line_comment'
+                buf = []
+                prefix = '#'
+                start_line = line
+            # any other char (incl. a lone '/') stays in code
+
+        elif state == 'string':
+            if c == '\\':
+                i += 2
+                # a backslash-newline still advances the line counter
+                if i - 1 < n and data[i - 1] == '\n':
+                    line += 1
+                continue
+            elif c == string_end:
+                state = 'code'
+
+        elif state == 'backtick_rawstring':
+            # No escapes; spans newlines; only a closing backtick ends it.
+            if c == '`':
+                state = 'code'
+
+        elif state == 'line_comment':
+            if c == '\n':
+                text = ''.join(buf)
+                if CJK.search(text):
+                    out.append((start_line, (prefix + text).rstrip()))
+                state = 'code'
+            else:
+                buf.append(c)
+
+        elif state == 'block_comment':
+            if c == '*' and nxt == '/':
+                text = ''.join(buf)
+                if CJK.search(text):
+                    first = text.split('\n', 1)[0]
+                    out.append((start_line, ('/*' + first).rstrip()))
+                state = 'code'
+                i += 2
+                continue
+            else:
+                buf.append(c)
+
+        if c == '\n':
+            line += 1
+        i += 1
+
+    # Unterminated trailing comment (EOF without newline / closing */).
+    if state == 'line_comment':
+        text = ''.join(buf)
+        if CJK.search(text):
+            out.append((start_line, (prefix + text).rstrip()))
+    elif state == 'block_comment':
+        text = ''.join(buf)
+        if CJK.search(text):
+            first = text.split('\n', 1)[0]
+            out.append((start_line, ('/*' + first).rstrip()))
+
+    return out
+
+
+def _json_line_for(raw, value):
+    """Best-effort: 1-based line of a "Comment" value containing CJK.
+
+    Scan raw text for a "Comment" key whose value substring matches. Falls
+    back to scanning for the value substring alone, else 1.
+    """
+    lines = raw.splitlines()
+    for idx, ln in enumerate(lines, 1):
+        if '"Comment"' in ln and value in ln:
+            return idx
+    for idx, ln in enumerate(lines, 1):
+        if value in ln:
+            return idx
+    return 1
+
+
+def json_hits(path):
+    """Find CJK in JSON ``Comment`` string values; report real line numbers."""
+    out = []
+    raw = _read_or_fail(path)
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return out
+
+    def walk(o):
+        if isinstance(o, dict):
+            for k, v in o.items():
+                if k == 'Comment' and isinstance(v, str) and CJK.search(v):
+                    out.append((_json_line_for(raw, v), f'Comment: {v}'))
+                walk(v)
+        elif isinstance(o, list):
+            for x in o:
+                walk(x)
+
+    walk(data)
+    return out
+
+
+def hits_for(path):
+    if path.endswith('.go'):
+        return comment_hits(path, hash_line_comment=False,
+                            backtick_rawstring=True)
+    if path.endswith('.thrift'):
+        return comment_hits(path, hash_line_comment=True,
+                            backtick_rawstring=False)
+    if path.endswith('.json'):
+        return json_hits(path)
+    return []
+
+
+def main():
+    bad = 0
+    for path in (p.strip() for p in sys.stdin if p.strip()):
+        for n, text in sorted(set(hits_for(path))):
+            bad += 1
+            print(f'{path}:{n}: {text}')
+
+    if bad:
+        print(f'\n[check-comment-i18n] {bad} CJK comment(s) found — '
+              f'comments must be English.', file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/templates/scripts/check-comment-i18n.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# check-comment-i18n.sh — fail if CJK appears in Go code comments. A COMMENT
+# gate for Go source only: runtime strings / prompts are out of scope, and so
+# are the external-facing API contracts (IDL .thrift comments, OpenAPI, and
+# errno JSON Comment fields) which are intentionally kept in Chinese for
+# external integrators. Tokenization lives in the committed
+# check-comment-i18n.py; this wrapper only does file discovery + exclusion.
+#
+# Usage: check-comment-i18n.sh [PATH...]   (default: .)
+#   - A PATH that is a directory is scanned recursively for *.go files.
+#   - A PATH that is a FILE is included iff it is a *.go file. The same exclude
+#     regex applies.
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+# Default to whole tree when no path given.
+if [ "$#" -eq 0 ]; then
+  set -- .
+fi
+
+EXCLUDE='thrift_gen|\.pb\.go|_gen\.go|mock_|/mocks/|zz_generated|/vendor/|(^|/)\.claude/|(^|/)\.codex/'
+
+discover() {
+  local target
+  for target in "$@"; do
+    if [ -d "$target" ]; then
+      find "$target" -type f -name '*.go' 2>/dev/null
+    elif [ -f "$target" ]; then
+      case "$target" in
+        *.go) printf '%s\n' "$target" ;;
+      esac
+    fi
+  done
+}
+
+discover "$@" \
+  | { grep -vE "$EXCLUDE" || true; } \
+  | python3 "$HERE/check-comment-i18n.py"

package/templates/scripts/check-doc-refs.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Verify that repo paths cited in component docs (docs/NN-*.md) exist on disk.
+#
+# This complements check-docs.sh (which only lints filename/title/numbering
+# structure) with a lightweight content<->code guard: it is the cheapest way to
+# catch the "doc names a file/dir that was renamed or deleted" drift class that
+# previously slipped through CI.
+#
+# Scope / non-goals:
+#   - Only docs/NN-*.md (component & architecture docs). ADRs are immutable
+#     historical records and are intentionally NOT scanned.
+#   - configs/ is out of scope (runtime artifacts; owned by coding-deploy-config).
+#   - Removal / placeholder / 规划中 lines are ignored on purpose.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/doc-drift.sh
+. scripts/lib/doc-drift.sh
+
+echo "==> Checking repo path references in docs/NN-*.md resolve on disk..."
+
+broken=0
+for f in docs/[0-9]*-*.md; do
+    [[ -f "$f" ]] || continue
+    while IFS= read -r hit; do
+        [[ -z "$hit" ]] && continue
+        echo "  [FAIL] doc references missing path -> ${hit}"
+        broken=$((broken + 1))
+    done < <(doc_drift_check_paths "$f")
+done
+
+if [[ "$broken" -gt 0 ]]; then
+    echo
+    echo "  ${broken} broken path reference(s). Fix the path in the doc, or — if the"
+    echo "  path is intentionally absent — phrase it as a removal/placeholder/规划中,"
+    echo "  which this check skips. configs/ paths are out of scope."
+    exit 1
+fi
+
+echo "  [OK] all repo path references resolve"

package/templates/scripts/check-docs.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Validate filename pattern, title-number alignment, and number uniqueness for:
+#   docs/NN-*.md         (component/architecture, 2-digit prefix)
+#   docs/adr/NNNN-*.md   (architecture decisions, 4-digit prefix)
+#
+# Status field (Accepted/Deprecated/...) is enforced by scripts/check-adr.sh.
+# See docs/adr/CONVENTIONS.md.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Grandfathered violations — pending cleanup tracked in CONVENTIONS.md.
+# Removing an entry here MUST coincide with cleaning up CONVENTIONS.md table
+# AND scripts/check-adr.sh GRANDFATHERED if applicable.
+GRANDFATHERED=()
+
+is_grandfathered() {
+  local f=$1
+  for g in "${GRANDFATHERED[@]+"${GRANDFATHERED[@]}"}"; do
+    [ "$f" = "$g" ] && return 0
+  done
+  return 1
+}
+
+VIOLATIONS=0
+GRANDFATHERED_HITS=0
+
+# check_dir <directory> <digit-count>
+check_dir() {
+  local dir=$1 digits=$2
+  local seen_nums=""
+  local fname_pattern="^[0-9]{${digits}}-[a-z0-9-]+\.md$"
+  local title_pattern="^#[[:space:]]+([0-9]+)[[:space:]]+-[[:space:]]+.+$"
+
+  for f in "$dir"/[0-9]*.md; do
+    [ -f "$f" ] || continue
+    local base num title title_num grandfather_msg
+    base=$(basename "$f")
+    grandfather_msg=""
+    is_grandfathered "$f" && grandfather_msg=" (cleanup tracked in CONVENTIONS.md)"
+
+    # 1. Filename pattern
+    if ! [[ "$base" =~ $fname_pattern ]]; then
+      if is_grandfathered "$f"; then
+        echo "  [GRANDFATHERED] $f — filename does not match ^[0-9]{${digits}}-[a-z0-9-]+\\.md\$$grandfather_msg"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        echo "  [VIOLATION]     $f — filename does not match ^[0-9]{${digits}}-[a-z0-9-]+\\.md\$"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+      continue
+    fi
+
+    num=${base:0:$digits}
+
+    # 2. Number uniqueness within directory
+    if echo "$seen_nums" | grep -qx "$num"; then
+      echo "  [VIOLATION]     $f — number $num already used in $dir"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    else
+      seen_nums="$seen_nums"$'\n'"$num"
+    fi
+
+    # 3. Title pattern + number alignment
+    title=$(head -1 "$f")
+    if ! [[ "$title" =~ $title_pattern ]]; then
+      if is_grandfathered "$f"; then
+        echo "  [GRANDFATHERED] $f — title does not match '# NUM - ...'$grandfather_msg"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        echo "  [VIOLATION]     $f — title '$title' does not match '# NUM - ...'"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+      continue
+    fi
+    title_num=${BASH_REMATCH[1]}
+    if [ "$title_num" != "$num" ]; then
+      if is_grandfathered "$f"; then
+        echo "  [GRANDFATHERED] $f — title number '$title_num' ≠ filename '$num'$grandfather_msg"
+        GRANDFATHERED_HITS=$((GRANDFATHERED_HITS + 1))
+      else
+        echo "  [VIOLATION]     $f — title number '$title_num' does not match filename '$num'"
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    fi
+  done
+}
+
+check_dir docs 2
+check_dir docs/adr 4
+
+if [ $VIOLATIONS -eq 0 ]; then
+  if [ $GRANDFATHERED_HITS -gt 0 ]; then
+    echo "  [OK]  no new violations (${GRANDFATHERED_HITS} grandfathered awaiting cleanup)"
+  else
+    echo "  [OK]  filename / title / numbering all consistent"
+  fi
+  exit 0
+fi
+
+echo
+echo "  ${VIOLATIONS} new violation(s). See docs/adr/CONVENTIONS.md."
+exit 1