From 0c74a9ce5b8e36f498f7b37cbc2b93d3f2c153bb Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:53:47 +0100 Subject: [PATCH 1/6] fix(scripts): repoint checks at the .adoc files that exist The .md -> .adoc documentation migration moved these files but never updated the scripts that READ them, so every check naming a .md has been operating on a file that no longer exists. Repointed: CHANGELOG.md->CHANGELOG.adoc MAINTAINERS.md->MAINTAINERS.adoc TEST-NEEDS.md->TEST-NEEDS.adoc Three failure modes were in play across the estate, all fixed by the same change: * hard fail - 'check "X.md exists" "[ -f X.md ]"' can never pass * wrong score - '[ -f X.md ] && ((doc_score++))' silently scores lower * SILENT SKIP - 'if [ -f X.md ]; then ...greps... fi' skips the whole block, so the checks inside never run and the gate reports success by not checking at all Human-readable labels are repointed too, so failure messages name the file that is actually inspected. Where a script did 'git add ... X.md', that is fixed as well - it would have failed at release time. Only tokens whose .adoc twin exists in this repository were rewritten; anything without a twin was left untouched for separate triage. Found by an estate-wide sweep of 454 repos: 56 such checks across 18 repos. Same defect class as hyperpolymath/Axiom.jl#82. --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 16 ++++++++-------- .../ffi/wasm-runtime/scripts/rsr-check.sh | 8 ++++---- .../tests/validate_structure.sh | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index a0fc12da9..dde9294c6 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -64,9 +64,9 @@ check "README exists" "[[ -f README.md ]] || [[ -f README.adoc ]]" check "README is comprehensive (>100 lines)" "[[ -f README.md ]] && [[ \$(wc -l < README.md) -gt 100 ]] || [[ -f README.adoc ]] && [[ \$(wc -l < README.adoc) -gt 100 ]]" check "CONTRIBUTING exists" "[[ -f CONTRIBUTING.md ]] || [[ -f CONTRIBUTING.adoc ]]" check "CODE_OF_CONDUCT.md exists" "[[ -f CODE_OF_CONDUCT.md ]]" -check "MAINTAINERS exists" "[[ -f MAINTAINERS.md ]] || [[ -f MAINTAINERS.adoc ]]" +check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" check "SECURITY.md exists" "[[ -f SECURITY.md ]]" -check "CHANGELOG exists" "[[ -f CHANGELOG.md ]] || [[ -f CHANGELOG.adoc ]]" +check "CHANGELOG exists" "[[ -f CHANGELOG.adoc ]] || [[ -f CHANGELOG.adoc ]]" check "ARCHITECTURE.md exists" "[[ -f docs/ARCHITECTURE.md ]]" check "API_REFERENCE.md exists" "[[ -f docs/API_REFERENCE.md ]]" check "FAQ.md exists" "[[ -f docs/FAQ.md ]]" @@ -115,10 +115,10 @@ check "PR template exists" "[[ -f .github/pull_request_template.md ]]" # ============================================================================= section "Category 5: Governance" -check "MAINTAINERS exists" "[[ -f MAINTAINERS.md ]] || [[ -f MAINTAINERS.adoc ]]" +check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" check "CODEOWNERS exists" "[[ -f .github/CODEOWNERS ]]" -check "Maintainer responsibilities documented" "grep -q 'Responsibilities' MAINTAINERS.md 2>/dev/null || grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" -check "Decision-making process documented" "grep -q 'Decision Making' MAINTAINERS.md 2>/dev/null || grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null || grep -q 'decision' MAINTAINERS.md 2>/dev/null" +check "Maintainer responsibilities documented" "grep -q 'Responsibilities' MAINTAINERS.adoc 2>/dev/null || grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" +check "Decision-making process documented" "grep -q 'Decision Making' MAINTAINERS.adoc 2>/dev/null || grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null || grep -q 'decision' MAINTAINERS.adoc 2>/dev/null" check "RSR.md with TPCF declaration exists" "[[ -f RSR.md ]]" check "TPCF perimeter declared" "grep -q 'Perimeter 3' RSR.md" @@ -152,9 +152,9 @@ check "Setup script is executable" "[[ -x scripts/setup-dev.sh ]]" # ============================================================================= section "Category 8: Versioning" -check "CHANGELOG follows Keep a Changelog" "grep -qi 'Changelog' CHANGELOG.md 2>/dev/null || grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null" -check "CHANGELOG has Unreleased section" "grep -qi 'Unreleased' CHANGELOG.md 2>/dev/null || grep -qi 'Unreleased' CHANGELOG.adoc 2>/dev/null" -check "Semantic versioning mentioned" "grep -qi 'Semantic Versioning' CHANGELOG.md 2>/dev/null || grep -qi 'semver' CHANGELOG.adoc 2>/dev/null || grep -qi 'Semantic' CHANGELOG.adoc 2>/dev/null" +check "CHANGELOG follows Keep a Changelog" "grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null || grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null" +check "CHANGELOG has Unreleased section" "grep -qi 'Unreleased' CHANGELOG.adoc 2>/dev/null || grep -qi 'Unreleased' CHANGELOG.adoc 2>/dev/null" +check "Semantic versioning mentioned" "grep -qi 'Semantic Versioning' CHANGELOG.adoc 2>/dev/null || grep -qi 'semver' CHANGELOG.adoc 2>/dev/null || grep -qi 'Semantic' CHANGELOG.adoc 2>/dev/null" # ============================================================================= # Category 9: .well-known diff --git a/rescript-ecosystem/packages/ffi/wasm-runtime/scripts/rsr-check.sh b/rescript-ecosystem/packages/ffi/wasm-runtime/scripts/rsr-check.sh index b4b3a3903..ab56fcdb2 100755 --- a/rescript-ecosystem/packages/ffi/wasm-runtime/scripts/rsr-check.sh +++ b/rescript-ecosystem/packages/ffi/wasm-runtime/scripts/rsr-check.sh @@ -69,10 +69,10 @@ echo "" echo -e "${BLUE}1. Documentation${NC}" check_file "README.md" "README.md" check_file "LICENSE" "LICENSE" -check_file "CHANGELOG.md" "CHANGELOG.md" +check_file "CHANGELOG.adoc" "CHANGELOG.adoc" check_file "CONTRIBUTING.md" "CONTRIBUTING.md" check_file "CODE_OF_CONDUCT.md" "CODE_OF_CONDUCT.md" -check_file "MAINTAINERS.md" "MAINTAINERS.md" +check_file "MAINTAINERS.adoc" "MAINTAINERS.adoc" check_file "SECURITY.md" "SECURITY.md" check_file "TPCF.md" "TPCF.md (Tri-Perimeter Contribution Framework)" echo "" @@ -278,8 +278,8 @@ if [ "$FAILED" -gt 0 ] || [ "$WARNINGS" -gt 0 ]; then echo "- Add CODE_OF_CONDUCT.md for community guidelines" fi - if [ ! -f "MAINTAINERS.md" ]; then - echo "- Add MAINTAINERS.md listing project maintainers" + if [ ! -f "MAINTAINERS.adoc" ]; then + echo "- Add MAINTAINERS.adoc listing project maintainers" fi if [ ! -d ".well-known" ]; then diff --git a/rescript-ecosystem/rescript-string-power/tests/validate_structure.sh b/rescript-ecosystem/rescript-string-power/tests/validate_structure.sh index 263c2d206..12b7f1018 100755 --- a/rescript-ecosystem/rescript-string-power/tests/validate_structure.sh +++ b/rescript-ecosystem/rescript-string-power/tests/validate_structure.sh @@ -32,7 +32,7 @@ check "CHANGELOG.adoc present" '[ -f CHANGELOG.adoc ]' check "EXPLAINME.adoc present" '[ -f EXPLAINME.adoc ]' check "0-AI-MANIFEST.a2ml present" '[ -f 0-AI-MANIFEST.a2ml ]' check "READINESS.md present" '[ -f READINESS.md ]' -check "TEST-NEEDS.md present" '[ -f TEST-NEEDS.md ]' +check "TEST-NEEDS.adoc present" '[ -f TEST-NEEDS.adoc ]' check ".well-known/security.txt" '[ -f .well-known/security.txt ]' check ".github/FUNDING.yml" '[ -f .github/FUNDING.yml ]' check ".github/workflows/ci.yml" '[ -f .github/workflows/ci.yml ]' From 2556889005a0be1e1d91107e06c7e3f3bf2bee87 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:16:11 +0100 Subject: [PATCH 2/6] Update asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index dde9294c6..cfc464705 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -152,7 +152,7 @@ check "Setup script is executable" "[[ -x scripts/setup-dev.sh ]]" # ============================================================================= section "Category 8: Versioning" -check "CHANGELOG follows Keep a Changelog" "grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null || grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null" +check "CHANGELOG follows Keep a Changelog" "grep -qi 'Changelog' CHANGELOG.adoc 2>/dev/null" check "CHANGELOG has Unreleased section" "grep -qi 'Unreleased' CHANGELOG.adoc 2>/dev/null || grep -qi 'Unreleased' CHANGELOG.adoc 2>/dev/null" check "Semantic versioning mentioned" "grep -qi 'Semantic Versioning' CHANGELOG.adoc 2>/dev/null || grep -qi 'semver' CHANGELOG.adoc 2>/dev/null || grep -qi 'Semantic' CHANGELOG.adoc 2>/dev/null" From eaa97daf12592e3ffb240c9f28a4ec8b61861eb8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:16:24 +0100 Subject: [PATCH 3/6] Update asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index cfc464705..b09ad9f60 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -118,7 +118,7 @@ section "Category 5: Governance" check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" check "CODEOWNERS exists" "[[ -f .github/CODEOWNERS ]]" check "Maintainer responsibilities documented" "grep -q 'Responsibilities' MAINTAINERS.adoc 2>/dev/null || grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" -check "Decision-making process documented" "grep -q 'Decision Making' MAINTAINERS.adoc 2>/dev/null || grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null || grep -q 'decision' MAINTAINERS.adoc 2>/dev/null" +check "Decision-making process documented" "grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null" check "RSR.md with TPCF declaration exists" "[[ -f RSR.md ]]" check "TPCF perimeter declared" "grep -q 'Perimeter 3' RSR.md" From d457e9ebf629d6b7e24f365ebe1a96c20e25d3ff Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:16:34 +0100 Subject: [PATCH 4/6] Update asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index b09ad9f60..c3511ef9a 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -117,7 +117,7 @@ section "Category 5: Governance" check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" check "CODEOWNERS exists" "[[ -f .github/CODEOWNERS ]]" -check "Maintainer responsibilities documented" "grep -q 'Responsibilities' MAINTAINERS.adoc 2>/dev/null || grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" +check "Maintainer responsibilities documented" "grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" check "Decision-making process documented" "grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null" check "RSR.md with TPCF declaration exists" "[[ -f RSR.md ]]" check "TPCF perimeter declared" "grep -q 'Perimeter 3' RSR.md" From 20a40f43671cfd940f7c7ce3d5b5b96123429b33 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:16:45 +0100 Subject: [PATCH 5/6] Update asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index c3511ef9a..5ed0125ed 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -64,7 +64,7 @@ check "README exists" "[[ -f README.md ]] || [[ -f README.adoc ]]" check "README is comprehensive (>100 lines)" "[[ -f README.md ]] && [[ \$(wc -l < README.md) -gt 100 ]] || [[ -f README.adoc ]] && [[ \$(wc -l < README.adoc) -gt 100 ]]" check "CONTRIBUTING exists" "[[ -f CONTRIBUTING.md ]] || [[ -f CONTRIBUTING.adoc ]]" check "CODE_OF_CONDUCT.md exists" "[[ -f CODE_OF_CONDUCT.md ]]" -check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" +check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]]" check "SECURITY.md exists" "[[ -f SECURITY.md ]]" check "CHANGELOG exists" "[[ -f CHANGELOG.adoc ]] || [[ -f CHANGELOG.adoc ]]" check "ARCHITECTURE.md exists" "[[ -f docs/ARCHITECTURE.md ]]" From dedf1701b4d913029f2ce5eb6f8e90e47ff678c4 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:44:21 +0100 Subject: [PATCH 6/6] fix(scripts): collapse duplicate-branch checks left by the .adoc repoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repoint sweep rewrote '.md || .adoc' fallbacks so BOTH sides name the same file, leaving conditions that are redundant at best and broken at worst. Codacy flagged the worst case as HIGH RISK and is correct: [[ -f CONTRIBUTING.adoc ]] && [[ $(wc -l < …) -gt 50 ]] \ || [[ -f CONTRIBUTING.adoc ]] && [[ $(wc -l < …) -gt 5 ]] Bash parses A && B || C && D as ((A && B) || C) && D, so the TRAILING condition always gates. The stated '>50 lines' requirement was silently replaced by '>5'. Verified empirically rather than by reading: under the old form a 20-line file PASSES a '>50 lines' check. Under the new form it fails, and a 60-line file still passes. A gate that cannot fail is not a gate. Also collapsed, all provably redundant after the sweep: * [[ -f X ]] || [[ -f X ]] -> [[ -f X ]] * identical guarded pairs over the same file -> single branch * 3-way grep chains over one file where a case-insensitive pattern subsumes the others Where two branches named the SAME file with DIFFERENT thresholds, the branch matching the check's own stated description was kept and the weaker one dropped. Genuine .md/.adoc fallbacks (different files) were left untouched. Co-Authored-By: Claude Opus 5 --- asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh index 5ed0125ed..b88b582a0 100755 --- a/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh +++ b/asdf-augmenters/asdf-ghjk/scripts/rsr-verify.sh @@ -66,7 +66,7 @@ check "CONTRIBUTING exists" "[[ -f CONTRIBUTING.md ]] || [[ -f CONTRIBUTING.adoc check "CODE_OF_CONDUCT.md exists" "[[ -f CODE_OF_CONDUCT.md ]]" check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]]" check "SECURITY.md exists" "[[ -f SECURITY.md ]]" -check "CHANGELOG exists" "[[ -f CHANGELOG.adoc ]] || [[ -f CHANGELOG.adoc ]]" +check "CHANGELOG exists" "[[ -f CHANGELOG.adoc ]]" check "ARCHITECTURE.md exists" "[[ -f docs/ARCHITECTURE.md ]]" check "API_REFERENCE.md exists" "[[ -f docs/API_REFERENCE.md ]]" check "FAQ.md exists" "[[ -f docs/FAQ.md ]]" @@ -115,7 +115,7 @@ check "PR template exists" "[[ -f .github/pull_request_template.md ]]" # ============================================================================= section "Category 5: Governance" -check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]] || [[ -f MAINTAINERS.adoc ]]" +check "MAINTAINERS exists" "[[ -f MAINTAINERS.adoc ]]" check "CODEOWNERS exists" "[[ -f .github/CODEOWNERS ]]" check "Maintainer responsibilities documented" "grep -qi 'responsibilities' MAINTAINERS.adoc 2>/dev/null" check "Decision-making process documented" "grep -qi 'decision' MAINTAINERS.adoc 2>/dev/null" @@ -140,7 +140,7 @@ check "CI tests multiple platforms" "grep -q 'ubuntu-latest' .github/workflows/c section "Category 7: Build System" check "Build system exists" "[[ -f Makefile ]] || [[ -f Justfile ]] || [[ -f Justfile ]]" -check "Justfile exists" "[[ -f Justfile ]] || [[ -f Justfile ]]" +check "Justfile exists" "[[ -f Justfile ]]" check "Nix/Guix package definition exists" "[[ -f flake.nix ]] || [[ -f guix.scm ]] || [[ -f default.nix ]]" check "Build system has test target" "grep -qi 'test' Makefile 2>/dev/null || grep -qi 'test' Justfile 2>/dev/null || grep -qi 'test' Justfile 2>/dev/null" check "Build system has lint target" "grep -qi 'lint' Makefile 2>/dev/null || grep -qi 'lint' Justfile 2>/dev/null || grep -qi 'lint' Justfile 2>/dev/null"