From ada7794187f2dc642f5bae237526f5432fbcefd6 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Fri, 18 Sep 2026 13:50:25 +0000 Subject: [PATCH] =?UTF-8?q?fix(docs-gate):=20accept=20root=20CONTRIBUTING.?= =?UTF-8?q?adoc=20=E2=80=94=2094%=20of=20failures=20were=20false=20positiv?= =?UTF-8?q?es?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `have CONTRIBUTING.md 3-practice/CONTRIBUTING.adoc` never accepted a root CONTRIBUTING.adoc, even though this script's own header states the estate policy is "AsciiDoc is the default" and README/LICENSE both accept .adoc. The CONTRIBUTING cutoff armed itself on 2026-08-21 (ENFORCE_CONTRIBUTING_FROM), so as of today this gate blocks. Measured blast radius, 2026-09-18, random sample of 40 repos: passes the gate 6 FALSE POSITIVE (.adoc only) 32 genuinely missing the document 2 i.e. 32/34 = 94% of the repos this gate reports non-compliant do have the document, at the path the estate actually uses. Every 7 of the currently conflicted PR repos (bqniser, mylangiser, nextgen-databases, nimiser, phronesiser, pimcore-fortress, tlaiser) fail on this and on nothing else. The #505 fixture suite did not catch it: "alternate extensions accepted" places CONTRIBUTING.adoc only under 3-practice/, never at the root. Adds two fixtures — root CONTRIBUTING.adoc passes post-cutoff, and still warns-then-blocks when genuinely absent. Reverting just the gate line makes the first fixture fail (24/24 -> 23/1), so it is a real regression test. --- scripts/check-docs-presence.sh | 11 +++++++++-- scripts/tests/governance-gates-505-test.sh | 14 ++++++++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) 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" \