Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.8 KB
Raw Blame
#!/usr/bin/env bash
# scripts/check-key-files-current-state.sh — the anti-disease guard.
#
# CLAUDE.md grew to ~592KB / ~147k tokens (auto-loaded every session) once its
# per-file index became append-only: one `**vX.Y.Z (#NNN):**` clause per release
# per file. This guard makes that recurrence structurally impossible. A written
# rule caused the disease; a CI guard cures it.
#
# THREE HARD GATES (fail the build):
#   1. Bolded-release-clause ban — the reference docs (KEY_FILES.md + key-files/*,
#      docs/architecture/thin-client.md, docs/TESTING.md) describe CURRENT behavior
#      only. Release history lives in CHANGELOG.md + git. The bolded `**v0.<digit>`
#      marker is the disease signature; it must not appear in those docs. Plain prose
#      ("as of pgvector 0.7", "Postgres 11+") is fine — only the bolded release
#      marker is banned, so this never false-fires on legitimate version mentions.
#   2. Size caps for CLAUDE.md, the index, each subsystem and
#      docs/TESTING.md. The TESTING.md cap is a ratchet: lower it when the file
#      shrinks, never raise it; detail moves next to its code instead. A subsystem
#      page at its cap continues on a new page linked from its last line, not
#      on an unrelated page.
#   3. One reference bullet per src file across the index and subsystems — a cherry-pick that keeps both sides
#      of a hunk leaves two "- `src/x.ts`" bullets describing two different
#      "current states" for one file. Merge into the survivor, never append a twin.
#
# SOFT WARNS (stderr, non-fatal): prose history markers that suggest narration
# creeping back ("pre-fix", ", then v0.", "superseded by") in the reference docs.
#
# Usage:
#   bash scripts/check-key-files-current-state.sh
#
# Env overrides (for the guard's own test):
#   GBRAIN_DOC_GUARD_ROOT        repo root to scan (default: script's ../)
#   GBRAIN_CLAUDE_MD_MAX_BYTES   CLAUDE.md hard cap (default: 35000)
#   GBRAIN_TESTING_MD_MAX_BYTES  docs/TESTING.md hard cap (default: 120000)
#
# Exit codes:
#   0   clean
#   1   a hard gate failed

set -uo pipefail

ROOT="${GBRAIN_DOC_GUARD_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
MAX_BYTES="${GBRAIN_CLAUDE_MD_MAX_BYTES:-35000}"
TESTING_MAX_BYTES="${GBRAIN_TESTING_MD_MAX_BYTES:-120000}"

# Reference docs that MUST stay current-state (history-free).
REFERENCE_DOCS=(
  "docs/architecture/KEY_FILES.md"
  "docs/architecture/thin-client.md"
  "docs/TESTING.md"
)

shopt -s nullglob
KEY_FILE_DOCS=()
if [ -f "$ROOT/docs/architecture/KEY_FILES.md" ]; then
  KEY_FILE_DOCS+=("$ROOT/docs/architecture/KEY_FILES.md")
fi
for doc in "$ROOT"/docs/architecture/key-files/*.md; do
  REFERENCE_DOCS+=("${doc#"$ROOT/"}")
  KEY_FILE_DOCS+=("$doc")
done

fail=0

# ── Gate 1: bolded release-clause ban ──────────────────────────────────────
for rel in "${REFERENCE_DOCS[@]}"; do
  doc="$ROOT/$rel"
  [ -f "$doc" ] || continue
  hits=$(grep -nE '\*\*v0\.[0-9]' "$doc" || true)
  if [ -n "$hits" ]; then
    fail=1
    echo "FAIL: $rel contains bolded release-clause markers (append-only history is the disease this guard prevents)." >&2
    echo "      Reference docs describe CURRENT behavior only; release history goes in CHANGELOG.md + git." >&2
    echo "      Collapse each version-clause chain into the single current truth. Offending lines:" >&2
    printf '%s\n' "$hits" | sed 's/^/        /' | cut -c1-140 >&2
  fi
done

# ── Gate 2: CLAUDE.md size cap ─────────────────────────────────────────────
claude="$ROOT/CLAUDE.md"
if [ -f "$claude" ]; then
  bytes=$(wc -c < "$claude" | tr -d ' ')
  if [ "$bytes" -gt "$MAX_BYTES" ]; then
    fail=1
    echo "FAIL: CLAUDE.md is $bytes bytes, over the $MAX_BYTES cap." >&2
    echo "      CLAUDE.md is orientation + resolver, not the implementation spec. Per-file/" >&2
    echo "      per-command/per-test detail belongs in the on-demand reference docs" >&2
    echo "      (docs/architecture/KEY_FILES.md, docs/TESTING.md, docs/RELEASING.md), not here." >&2
  fi
fi

for spec in "docs/architecture/KEY_FILES.md:10000"; do
  rel="${spec%:*}"
  cap="${spec##*:}"
  [ -f "$ROOT/$rel" ] || continue
  bytes=$(wc -c < "$ROOT/$rel" | tr -d ' ')
  if [ "$bytes" -gt "$cap" ]; then
    fail=1
    echo "FAIL: $rel is $bytes bytes, over the $cap cap. Move detail to a linked reference." >&2
  fi
done
testing="$ROOT/docs/TESTING.md"
if [ -f "$testing" ]; then
  bytes=$(wc -c < "$testing" | tr -d ' ')
  if [ "$bytes" -gt "$TESTING_MAX_BYTES" ]; then
    fail=1
    echo "FAIL: docs/TESTING.md is $bytes bytes, over the $TESTING_MAX_BYTES cap (a ratchet: it only goes down)." >&2
    echo "      Trim: move subsystem detail next to its code (a README beside the harness or module) and leave a" >&2
    echo "      two-line pointer; describe lanes and guards, not individual test files (each test's header does that)." >&2
    echo "      Docs: docs/TESTING.md#quick-start" >&2
  fi
fi
for doc in "$ROOT"/docs/architecture/key-files/*.md; do
  bytes=$(wc -c < "$doc" | tr -d ' ')
  if [ "$bytes" -gt 60000 ]; then
    fail=1
    echo "FAIL: ${doc#"$ROOT/"} is $bytes bytes, over the 60000 cap. Move its last entries to a continuation page that links back with [Previous entries](<page>.md), and link it from this page's last line; never raise the cap." >&2
  fi
done

# ── Gate 3: one KEY_FILES.md bullet per src file ───────────────────────────
# ponytail: KNOWN_DUP_PATHS seeds the pairs that pre-date the gate so it lands
# green; merge a pair and delete its entry here — never add to this list.
KNOWN_DUP_PATHS='src/cli.ts|src/commands/dream.ts|src/core/context/resolve-ipc.ts|src/core/context/turn-context.ts|src/core/cycle/transcript-discovery.ts'
if [ "${#KEY_FILE_DOCS[@]}" -gt 0 ]; then
  dups=$(grep -h -oE '^- `src/[^`]+`' "${KEY_FILE_DOCS[@]}" | sort | uniq -d | grep -vE "^- \`($KNOWN_DUP_PATHS)\`$" || true)
  if [ -n "$dups" ]; then
    fail=1
    echo "FAIL: docs/architecture/KEY_FILES.md and its subsystems have more than one bullet for the same src file (two 'current states' for one file):" >&2
    printf '%s\n' "$dups" | sed 's/^/        /' >&2
    echo "      Fold the newer sentences into the existing bullet and delete the twin." >&2
  fi
fi

# ── Soft warns: prose history markers creeping into reference docs ──────────
for rel in "${REFERENCE_DOCS[@]}"; do
  doc="$ROOT/$rel"
  [ -f "$doc" ] || continue
  warns=$(grep -cnE ', then v0\.|superseded by|pre-fix|post-fix' "$doc" || true)
  if [ "${warns:-0}" -gt 0 ]; then
    echo "WARN: $rel has $warns prose history marker(s) ('pre-fix' / ', then v0.' / 'superseded by'). Prefer current-state phrasing." >&2
  fi
done

if [ "$fail" -ne 0 ]; then
  exit 1
fi
echo "check-key-files-current-state: ok (reference docs history-free; entry and subsystem docs within caps)"