diff --git a/scripts/check-docs-presence.sh b/scripts/check-docs-presence.sh index 031139e65..fcdc83758 100755 --- a/scripts/check-docs-presence.sh +++ b/scripts/check-docs-presence.sh @@ -24,7 +24,14 @@ # default; GitHub-required community-health files stay Markdown): # README.adoc | README.md # LICENSE | LICENSE.txt | LICENSE.md -# CONTRIBUTING.md | 3-practice/CONTRIBUTING.adoc +# CONTRIBUTING.md | CONTRIBUTING.adoc | 3-practice/CONTRIBUTING.adoc +# +# CONTRIBUTING.adoc at the repo root is accepted because the estate policy named +# above makes AsciiDoc the default, and it is what the estate actually uses: +# sampling 40 repos on 2026-09-18 found 32 carrying a root CONTRIBUTING.adoc and +# no CONTRIBUTING.md, versus 2 genuinely missing the document. Without it this +# gate failed 94% of the repos it reported as non-compliant, the day the +# CONTRIBUTING cutoff armed. # # Usage: check-docs-presence.sh [repo-root] # @@ -83,7 +90,7 @@ grace_missing="" have README.adoc README.md || blocking_missing="$blocking_missing README" have LICENSE LICENSE.txt LICENSE.md || blocking_missing="$blocking_missing LICENSE" -if ! have CONTRIBUTING.md 3-practice/CONTRIBUTING.adoc; then +if ! have CONTRIBUTING.md CONTRIBUTING.adoc 3-practice/CONTRIBUTING.adoc; then # String comparison is sound here: YYYY-MM-DD sorts chronologically, and both # operands are format-validated above. if [[ "$TODAY" < "$ENFORCE_CONTRIBUTING_FROM" ]]; then diff --git a/scripts/tests/governance-gates-505-test.sh b/scripts/tests/governance-gates-505-test.sh index b0c2d0688..e719abf0c 100755 --- a/scripts/tests/governance-gates-505-test.sh +++ b/scripts/tests/governance-gates-505-test.sh @@ -69,6 +69,20 @@ r=$(mkrepo docs-md README.md LICENSE.txt 3-practice/CONTRIBUTING.adoc) assert "alternate extensions accepted" 0 "✅ Core documentation present" \ env DOCS_TODAY="$AFTER" "$DOCS" "$r" +# Regression: AsciiDoc is the estate default and a root CONTRIBUTING.adoc is the +# dominant real-world layout (32 of 34 sampled non-compliant repos). This used to +# fail, so the gate reported 94% false positives once the cutoff armed on +# 2026-08-21. The "alternate extensions" case above did not catch it because it +# only ever placed CONTRIBUTING.adoc under 3-practice/. +r=$(mkrepo docs-adoc-root README.adoc LICENSE CONTRIBUTING.adoc) +assert "root CONTRIBUTING.adoc accepted (regression: 94% false positives)" 0 \ + "✅ Core documentation present" \ + env DOCS_TODAY="$AFTER" "$DOCS" "$r" +# ...and it must still be the grace-windowed document, not an unconditional pass. +assert "root CONTRIBUTING.adoc still warns pre-cutoff only when ABSENT" 0 \ + "NOT YET ENFORCED" \ + env DOCS_TODAY="$BEFORE" "$DOCS" "$(mkrepo docs-adoc-root-absent README.adoc LICENSE)" + # README/LICENSE are BLOCKING NOW — the grace window must not shelter them. r=$(mkrepo docs-no-readme LICENSE CONTRIBUTING.md) assert "missing README fails even pre-cutoff" 1 "Missing required documentation: README" \