fix(scripts): remove Python from doc freshness checks (#4978) (#4979)

Use strict pure-Bash proleptic-Gregorian validation and day numbering so the full 0001-01-01 through 9999-12-31 domain is independent of platform date parsing. Keep native date only as the default TODAY provider, with distinct provider-versus-override diagnostics.

Mark the real-process suite integration-only, harden Git Bash discovery and its child environment, and require native Linux, macOS, and Windows boundaries in PR CI.

Agent-Signature: codex-tui-gpt-5.6-sol-ultra on behalf of Ewen Cuthiell

Co-authored-by: matt wilkie <maphew@gmail.com>
This commit is contained in:
ecuthiell 2026-07-25 23:53:47 -06:00 • committed by GitHub
commit bbda695454
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 598 additions and 14 deletions

View file

@ -204,6 +204,25 @@ jobs:
path: ${{ runner.temp }}/cli-docs-freshness.patch
if-no-files-found: ignore
check-doc-freshness-platforms:
name: Check doc freshness (${{ matrix.os }})
runs-on: ${{ matrix.os }}
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- name: Set up Go
uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: 'go.mod'
- name: Exercise native date and Bash process boundary
run: go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts
pr-preflight-platforms:
name: PR preflight process (${{ matrix.os }})
runs-on: ${{ matrix.os }}
@ -767,6 +786,7 @@ jobs:
- check-version-consistency
- check-migration-hygiene
- check-doc-flags
- check-doc-freshness-platforms
- pr-preflight-platforms
- check-no-beads-changes
- detect-package-gates
@ -795,6 +815,7 @@ jobs:
CHECK_VERSION_CONSISTENCY
CHECK_MIGRATION_HYGIENE
CHECK_DOC_FLAGS
CHECK_DOC_FRESHNESS_PLATFORMS
PR_PREFLIGHT_PLATFORMS
CHECK_NO_BEADS_CHANGES
DETECT_PACKAGE_GATES
@ -815,6 +836,7 @@ jobs:
CHECK_VERSION_CONSISTENCY: ${{ needs.check-version-consistency.result }}
CHECK_MIGRATION_HYGIENE: ${{ needs.check-migration-hygiene.result }}
CHECK_DOC_FLAGS: ${{ needs.check-doc-flags.result }}
CHECK_DOC_FRESHNESS_PLATFORMS: ${{ needs.check-doc-freshness-platforms.result }}
PR_PREFLIGHT_PLATFORMS: ${{ needs.pr-preflight-platforms.result }}
CHECK_NO_BEADS_CHANGES: ${{ needs.check-no-beads-changes.result }}
DETECT_PACKAGE_GATES: ${{ needs.detect-package-gates.result }}

View file

@ -13,7 +13,9 @@ set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
MAX_AGE_DAYS="${DOC_FRESHNESS_MAX_AGE_DAYS:-90}"
TODAY="${DOC_FRESHNESS_TODAY:-$(date +%F)}"
TODAY="${DOC_FRESHNESS_TODAY:-}"
TODAY_SOURCE="override"
TODAY_DAY=""
ERRORS=0
DOCS=(
@ -27,21 +29,68 @@ DOCS=(
"engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/"
)
echo "Checking reference doc freshness markers..."
echo "Max age: ${MAX_AGE_DAYS} days"
echo "Today: ${TODAY}"
echo ""
date_day_number() {
local value="$1"
local value_pattern='^([0-9]{4})-([0-9]{2})-([0-9]{2})$'
local year
local month
local day
local max_day
local adjusted_year
local era
local year_of_era
local month_prime
local day_of_year
local day_of_era
[[ "$value" =~ $value_pattern ]] || return 1
year=$((10#${BASH_REMATCH[1]}))
month=$((10#${BASH_REMATCH[2]}))
day=$((10#${BASH_REMATCH[3]}))
(( year >= 1 && year <= 9999 )) || return 1
case "$month" in
1|3|5|7|8|10|12)
max_day=31
;;
4|6|9|11)
max_day=30
;;
2)
max_day=28
if (( year % 400 == 0 || (year % 4 == 0 && year % 100 != 0) )); then
max_day=29
fi
;;
*)
return 1
;;
esac
(( day >= 1 && day <= max_day )) || return 1
# Map the proleptic Gregorian date to a monotonic day number. March is
# month zero, so leap day sits at the end of each transformed year.
adjusted_year=$year
if (( month <= 2 )); then
adjusted_year=$((adjusted_year - 1))
fi
era=$((adjusted_year / 400))
year_of_era=$((adjusted_year - era * 400))
if (( month > 2 )); then
month_prime=$((month - 3))
else
month_prime=$((month + 9))
fi
day_of_year=$(((153 * month_prime + 2) / 5 + day - 1))
day_of_era=$((year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year))
printf '%s\n' "$((era * 146097 + day_of_era))"
}
date_age_days() {
local reviewed="$1"
python3 - "$reviewed" "$TODAY" <<'PY'
import datetime
import sys
local reviewed_day
reviewed = datetime.date.fromisoformat(sys.argv[1])
today = datetime.date.fromisoformat(sys.argv[2])
print((today - reviewed).days)
PY
reviewed_day="$(date_day_number "$1")" || return 1
printf '%s\n' "$((TODAY_DAY - reviewed_day))"
}
inventory_ref_for_doc() {
@ -61,6 +110,27 @@ path_exists_or_glob_matches() {
fi
}
if [[ -z "$TODAY" ]]; then
TODAY_SOURCE="provider"
if ! TODAY="$(date '+%Y-%m-%d' 2>/dev/null)"; then
echo "ERROR: check-doc-freshness could not determine today's date" >&2
exit 2
fi
fi
if ! TODAY_DAY="$(date_day_number "$TODAY")"; then
if [[ "$TODAY_SOURCE" == "provider" ]]; then
echo "ERROR: date returned an invalid current date: $TODAY" >&2
else
echo "ERROR: invalid DOC_FRESHNESS_TODAY date: $TODAY" >&2
fi
exit 2
fi
echo "Checking reference doc freshness markers..."
echo "Max age: ${MAX_AGE_DAYS} days"
echo "Today: ${TODAY}"
echo ""
for entry in "${DOCS[@]}"; do
IFS='|' read -r doc sources <<<"$entry"
doc_path="$PROJECT_ROOT/$doc"

View file

@ -0,0 +1,486 @@
//go:build integration
package scripts_test
import (
"fmt"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"testing"
)
var freshnessDocuments = []struct {
path string
sources []string
}{
{"docs/reference/configuration.md", []string{"cmd/bd/main.go", "cmd/bd/config.go", "internal/configfile/"}},
{"docs/getting-started/ide-setup.md", []string{"cmd/bd/setup*.go", "internal/recipes/"}},
{"docs/integrations/azure-devops.md", []string{"cmd/bd/ado*.go", "internal/ado/"}},
{"docs/reference/json-schema.md", []string{"cmd/bd/output.go", "cmd/bd/errors.go", "cmd/bd/protocol/json_contract_test.go"}},
{"docs/recovery/init-safety.md", []string{"cmd/bd/init.go", "cmd/bd/init_safety.go", "cmd/bd/init_safety_test.go"}},
{"engdocs/ERROR_HANDLING.md", []string{"cmd/bd/*.go", "cmd/bd/errors.go"}},
{"engdocs/LINTING.md", []string{".golangci.yml"}},
{"engdocs/design/otel/otel-data-model.md", []string{"internal/telemetry/", "internal/storage/dolt/store.go", "internal/compact/haiku.go", "cmd/bd/find_duplicates.go", "internal/hooks/"}},
}
type freshnessRun struct {
output string
err error
pythonInvoked bool
dateInvoked bool
}
const pythonPoisonFunction = `python3() {
printf 'invoked\n' >"$PYTHON_POISON_MARKER"
return 97
}
`
const brokenDateFunction = `
date() {
printf 'invoked\n' >"$DATE_BACKEND_MARKER"
return 69
}
`
const garbageDateFunction = `
date() {
printf 'invoked\n' >"$DATE_BACKEND_MARKER"
printf 'garbage\n'
}
`
const recordingNativeDateFunction = `
date() {
printf 'invoked\n' >"$DATE_BACKEND_MARKER"
command date "$@"
}
`
func TestDocFreshnessDoesNotRequirePython(t *testing.T) {
run := runDocFreshness(t, "2026-01-15", "2026-01-31", "90")
if run.err != nil {
t.Fatalf("check-doc-freshness failed without Python: %v\n%s", run.err, run.output)
}
if run.pythonInvoked {
t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output)
}
for _, want := range []string{
"PASS: Last reviewed marker is current: 2026-01-15 (16 days old)",
"PASSED: Reference doc freshness markers are current and checkable",
} {
if !strings.Contains(run.output, want) {
t.Fatalf("missing %q:\n%s", want, run.output)
}
}
}
func TestDocFreshnessBashProbeIgnoresStartupEnvironment(t *testing.T) {
if runtime.GOOS != "windows" {
t.Skip("Git Bash discovery is Windows-specific")
}
poison := filepath.Join(t.TempDir(), "poison.sh")
if err := os.WriteFile(poison, []byte("exit 97\n"), 0o600); err != nil {
t.Fatalf("write startup poison: %v", err)
}
t.Setenv("BASH_ENV", poison)
t.Setenv("ENV", poison)
if bash := docFreshnessBash(t); bash == "" {
t.Fatal("docFreshnessBash returned an empty executable")
}
}
func TestDocFreshnessPreservesDateDiagnostics(t *testing.T) {
tests := []struct {
name string
reviewed string
today string
maxAge string
want string
}{
{
name: "invalid date",
reviewed: "2026-02-30",
today: "2026-03-01",
maxAge: "90",
want: "FAIL: invalid Last reviewed date: 2026-02-30",
},
{
name: "year zero",
reviewed: "0000-01-01",
today: "2026-03-01",
maxAge: "90",
want: "FAIL: invalid Last reviewed date: 0000-01-01",
},
{
name: "future date",
reviewed: "2026-03-02",
today: "2026-03-01",
maxAge: "90",
want: "FAIL: Last reviewed date is in the future: 2026-03-02",
},
{
name: "stale date",
reviewed: "2025-01-01",
today: "2026-03-01",
maxAge: "30",
want: "FAIL: Last reviewed date is stale: 2025-01-01",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
run := runDocFreshness(t, test.reviewed, test.today, test.maxAge)
if exitCode(run.err) != 1 {
t.Fatalf("exit = %d, want 1; error=%v\n%s", exitCode(run.err), run.err, run.output)
}
if run.pythonInvoked {
t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output)
}
if !strings.Contains(run.output, test.want) {
t.Fatalf("missing %q:\n%s", test.want, run.output)
}
})
}
}
func TestDocFreshnessPreservesISODateBoundaries(t *testing.T) {
for _, value := range []string{"0001-01-01", "2000-02-29", "9999-12-31"} {
t.Run(value, func(t *testing.T) {
run := runDocFreshness(t, value, value, "90")
if run.err != nil {
t.Fatalf("check-doc-freshness rejected supported boundary %s: %v\n%s", value, run.err, run.output)
}
if !strings.Contains(run.output, "PASS: Last reviewed marker is current: "+value+" (0 days old)") {
t.Fatalf("missing boundary date result for %s:\n%s", value, run.output)
}
})
}
}
func TestDocFreshnessUsesProlepticGregorianLeapRules(t *testing.T) {
tests := []struct {
name string
reviewed string
today string
wantExit int
want string
}{
{
name: "common century",
reviewed: "1900-02-28",
today: "1900-03-01",
wantExit: 0,
want: "PASS: Last reviewed marker is current: 1900-02-28 (1 days old)",
},
{
name: "leap century",
reviewed: "2000-02-28",
today: "2000-03-01",
wantExit: 0,
want: "PASS: Last reviewed marker is current: 2000-02-28 (2 days old)",
},
{
name: "ordinary leap year",
reviewed: "2024-02-28",
today: "2024-03-01",
wantExit: 0,
want: "PASS: Last reviewed marker is current: 2024-02-28 (2 days old)",
},
{
name: "invalid common-century leap day",
reviewed: "1900-02-29",
today: "1900-03-01",
wantExit: 1,
want: "FAIL: invalid Last reviewed date: 1900-02-29",
},
{
name: "invalid month zero",
reviewed: "2026-00-01",
today: "2026-03-01",
wantExit: 1,
want: "FAIL: invalid Last reviewed date: 2026-00-01",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
run := runDocFreshness(t, test.reviewed, test.today, "90")
if exitCode(run.err) != test.wantExit {
t.Fatalf("exit = %d, want %d; error=%v\n%s", exitCode(run.err), test.wantExit, run.err, run.output)
}
if run.pythonInvoked {
t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output)
}
if !strings.Contains(run.output, test.want) {
t.Fatalf("missing %q:\n%s", test.want, run.output)
}
})
}
}
func TestDocFreshnessUsesNativeDefaultTodayProvider(t *testing.T) {
run := runDocFreshnessWithDefaultToday(t, "0001-01-01", "4000000", recordingNativeDateFunction)
if run.err != nil {
t.Fatalf("check-doc-freshness failed with native default TODAY: %v\n%s", run.err, run.output)
}
if !run.dateInvoked {
t.Fatalf("check-doc-freshness did not invoke native date for the default TODAY value:\n%s", run.output)
}
if run.pythonInvoked {
t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output)
}
if !strings.Contains(run.output, "PASSED: Reference doc freshness markers are current and checkable") {
t.Fatalf("missing successful default-TODAY result:\n%s", run.output)
}
}
func TestDocFreshnessReportsUnavailableTodayProvider(t *testing.T) {
run := runDocFreshnessWithDefaultToday(t, "2026-01-15", "90", brokenDateFunction)
if exitCode(run.err) != 2 {
t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output)
}
if !run.dateInvoked {
t.Fatalf("check-doc-freshness did not invoke date for the default TODAY value:\n%s", run.output)
}
if !strings.Contains(run.output, "ERROR: check-doc-freshness could not determine today's date") {
t.Fatalf("missing explicit TODAY provider diagnostic:\n%s", run.output)
}
if strings.Contains(run.output, "invalid Last reviewed date") {
t.Fatalf("broken TODAY provider was mislabeled as document data:\n%s", run.output)
}
}
func TestDocFreshnessReportsInvalidTodayProviderOutput(t *testing.T) {
run := runDocFreshnessWithDefaultToday(t, "2026-01-15", "90", garbageDateFunction)
if exitCode(run.err) != 2 {
t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output)
}
if !run.dateInvoked {
t.Fatalf("check-doc-freshness did not invoke date for the default TODAY value:\n%s", run.output)
}
if !strings.Contains(run.output, "ERROR: date returned an invalid current date: garbage") {
t.Fatalf("missing invalid-provider-output diagnostic:\n%s", run.output)
}
if strings.Contains(run.output, "DOC_FRESHNESS_TODAY") {
t.Fatalf("provider output was mislabeled as an override:\n%s", run.output)
}
}
func TestDocFreshnessReportsInvalidTodayOverride(t *testing.T) {
run := runDocFreshness(t, "2026-01-15", "garbage", "90")
if exitCode(run.err) != 2 {
t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output)
}
if run.dateInvoked {
t.Fatalf("check-doc-freshness invoked date despite an explicit TODAY override:\n%s", run.output)
}
if !strings.Contains(run.output, "ERROR: invalid DOC_FRESHNESS_TODAY date: garbage") {
t.Fatalf("missing invalid-override diagnostic:\n%s", run.output)
}
}
func runDocFreshness(t *testing.T, reviewed, today, maxAge string) freshnessRun {
t.Helper()
return runDocFreshnessWithDateFunction(t, reviewed, today, maxAge, "")
}
func runDocFreshnessWithDateFunction(t *testing.T, reviewed, today, maxAge, dateFunction string) freshnessRun {
t.Helper()
return runDocFreshnessProcess(t, reviewed, &today, maxAge, dateFunction)
}
func runDocFreshnessWithDefaultToday(t *testing.T, reviewed, maxAge, dateFunction string) freshnessRun {
t.Helper()
return runDocFreshnessProcess(t, reviewed, nil, maxAge, dateFunction)
}
func runDocFreshnessProcess(t *testing.T, reviewed string, today *string, maxAge, dateFunction string) freshnessRun {
t.Helper()
bash := docFreshnessBash(t)
root := newDocFreshnessFixture(t, reviewed)
markerDir := t.TempDir()
pythonMarker := filepath.Join(markerDir, "python-invoked")
dateMarker := filepath.Join(markerDir, "date-invoked")
bashEnvironment := filepath.Join(t.TempDir(), "bash-env.sh")
if err := os.WriteFile(bashEnvironment, []byte(pythonPoisonFunction+dateFunction), 0o600); err != nil {
t.Fatalf("write Python poison environment: %v", err)
}
cmd := exec.Command(
bash,
"--noprofile",
"--norc",
msysPath(filepath.Join(root, "scripts", "check-doc-freshness.sh")),
)
cmd.Dir = root
cmd.Env = []string{
"PATH=/usr/bin:/bin",
"HOME=" + msysPath(t.TempDir()),
"LC_ALL=C",
"LANG=C",
"BASH_ENV=" + msysPath(bashEnvironment),
"ENV=",
"DATE_BACKEND_MARKER=" + msysPath(dateMarker),
"DOC_FRESHNESS_MAX_AGE_DAYS=" + maxAge,
"PYTHON_POISON_MARKER=" + msysPath(pythonMarker),
}
if today != nil {
cmd.Env = append(cmd.Env, "DOC_FRESHNESS_TODAY="+*today)
}
output, runErr := cmd.CombinedOutput()
return freshnessRun{
output: string(output),
err: runErr,
pythonInvoked: docFreshnessMarkerExists(t, pythonMarker),
dateInvoked: docFreshnessMarkerExists(t, dateMarker),
}
}
func docFreshnessBash(t *testing.T) string {
t.Helper()
if runtime.GOOS != "windows" {
bash, err := exec.LookPath("bash")
if err != nil {
t.Fatalf("bash is required to exercise check-doc-freshness.sh: %v", err)
}
return bash
}
git, err := exec.LookPath("git.exe")
if err != nil {
t.Fatalf("Git for Windows is required to exercise check-doc-freshness.sh: %v", err)
}
execPathCommand := exec.Command(git, "--exec-path")
execPathCommand.Env = docFreshnessProbeEnv()
execPathOutput, err := execPathCommand.CombinedOutput()
if err != nil {
t.Fatalf("locate the Git for Windows installation: %v: %s", err, strings.TrimSpace(string(execPathOutput)))
}
execPath := filepath.Clean(strings.TrimSpace(string(execPathOutput)))
if !filepath.IsAbs(execPath) {
t.Fatalf("Git for Windows returned a non-absolute exec path: %q", execPath)
}
gitRoot := filepath.Clean(filepath.Join(execPath, "..", "..", ".."))
candidates := []string{
filepath.Join(gitRoot, "bin", "bash.exe"),
filepath.Join(gitRoot, "usr", "bin", "bash.exe"),
}
var diagnostics []string
for _, candidate := range candidates {
if _, err := os.Stat(candidate); err != nil {
diagnostics = append(diagnostics, fmt.Sprintf("%s: %v", candidate, err))
continue
}
probe := exec.Command(candidate, "--noprofile", "--norc", "-c", `
export BASH_ENV=
export ENV=
PATH=/usr/bin:/bin
export PATH
case "$(uname -s)" in
MINGW*|MSYS*) command -v date >/dev/null ;;
*) exit 1 ;;
esac
`)
probe.Env = docFreshnessProbeEnv()
if output, err := probe.CombinedOutput(); err == nil {
return candidate
} else {
diagnostics = append(diagnostics, fmt.Sprintf("%s: %v: %s", candidate, err, strings.TrimSpace(string(output))))
}
}
t.Fatalf("a working Git Bash date environment is required: %s", strings.Join(diagnostics, "; "))
return ""
}
func docFreshnessMarkerExists(t *testing.T, path string) bool {
t.Helper()
_, err := os.Stat(path)
if err == nil {
return true
}
if !os.IsNotExist(err) {
t.Fatalf("inspect marker %s: %v", path, err)
}
return false
}
func newDocFreshnessFixture(t *testing.T, reviewed string) string {
t.Helper()
root := t.TempDir()
repoRoot := sourceRepoRoot(t)
script, err := os.ReadFile(filepath.Join(repoRoot, "scripts", "check-doc-freshness.sh"))
if err != nil {
t.Fatalf("read check-doc-freshness.sh: %v", err)
}
writeFixtureFile(t, root, "scripts/check-doc-freshness.sh", string(script))
var inventory strings.Builder
for _, document := range freshnessDocuments {
inventoryRef := strings.TrimPrefix(strings.TrimPrefix(document.path, "docs/"), "engdocs/")
fmt.Fprintf(&inventory, "- `%s`\n", inventoryRef)
writeFixtureFile(t, root, document.path, fmt.Sprintf(
"Last reviewed: %s\nFreshness source: %s\n",
reviewed,
strings.Join(document.sources, ";"),
))
for _, source := range document.sources {
createFreshnessSource(t, root, source)
}
}
writeFixtureFile(t, root, "engdocs/DOC_INVENTORY.md", inventory.String())
return root
}
func createFreshnessSource(t *testing.T, root, source string) {
t.Helper()
if strings.HasSuffix(source, "/") {
if err := os.MkdirAll(filepath.Join(root, filepath.FromSlash(source)), 0o755); err != nil {
t.Fatalf("create source directory %s: %v", source, err)
}
return
}
source = strings.ReplaceAll(source, "*", "fixture")
source = strings.ReplaceAll(source, "?", "x")
writeFixtureFile(t, root, source, "")
}
func writeFixtureFile(t *testing.T, root, relative, body string) {
t.Helper()
path := filepath.Join(root, filepath.FromSlash(relative))
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatalf("create parent for %s: %v", relative, err)
}
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatalf("write %s: %v", relative, err)
}
}
func docFreshnessProbeEnv() []string {
env := make([]string, 0, len(os.Environ())+3)
for _, entry := range os.Environ() {
key, _, ok := strings.Cut(entry, "=")
if !ok {
continue
}
upperKey := strings.ToUpper(key)
if upperKey == "BASH_ENV" || upperKey == "ENV" || strings.HasPrefix(upperKey, "GIT_") {
continue
}
env = append(env, entry)
}
return append(env, "BASH_ENV=", "ENV=", "GIT_EXEC_PATH=")
}

View file

@ -50,6 +50,12 @@ make check-docs
The script currently checks the reference docs named in `engdocs/DOC_INVENTORY.md`: `CONFIG.md`, `SETUP.md`, `ADO_CONFIG.md`, `JSON_SCHEMA.md`, `RECOVERY.md`, `ERROR_HANDLING.md`, `LINTING.md`, and `design/otel/otel-data-model.md`. Each doc must be listed in the inventory, include a recent `Last reviewed:` marker, include a `Freshness source:` marker, and name source paths or globs that exist in the repository.
Set `DOC_FRESHNESS_MAX_AGE_DAYS` to override the default 90-day review window. Set `DOC_FRESHNESS_TODAY=YYYY-MM-DD` when testing date behaviour.
Date validation uses Bash integer arithmetic over the proleptic Gregorian
calendar, preserves the `0001-01-01` through `9999-12-31` ISO domain, and does
not require Python or platform-specific date parsing. The native `date` command
is used only to supply today's value when `DOC_FRESHNESS_TODAY` is unset. Pull
requests exercise the real process boundary on Linux, macOS, and Git Bash on
Windows.
### How it fits into the larger codebase