From 517a442a0d0b13261d497d7e98a495701b1c31a6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 02:01:13 +0000 Subject: [PATCH] fix(ci): repair doc-truthing guard after #614's .md->.adoc migration #614 migrated six status/history docs from .md to .adoc, but the doc-truthing guard kept the old .md paths in two places, turning main's `build` job red: - BANNERED_DOCS presence list -> "bannered doc is missing" for BACKEND-IMPLEMENTATION / COMPILER-CAPABILITIES / ALPHA-1-RELEASE-NOTES - over-claim ratchet baseline (tools/doc-overclaims.allow) -> "new over-claim(s)" for the migrated .adoc history/roadmap snapshots (identical already-blessed claims, now at .adoc paths + .adoc markup) Fix (hotfix + hardening): - Re-key the over-claim baseline to the migrated .adoc paths via `--update`: a 1:1 re-bless of identical historical/roadmap content, no new live over-claims. - Harden the presence check so it cannot re-break on a future migration: BANNERED_DOCS are now extension-less stems resolved to whichever of .adoc/.md is present (.adoc preferred). Verified: guard exits 0 on the merged tree; resolver tested for the .adoc / .md / neither cases. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Lz7pRcec2Z3tVtaAhvB3M8 --- tools/check-doc-truthing.sh | 23 ++++++++++++++++------- tools/doc-overclaims.allow | 18 +++++++++--------- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/tools/check-doc-truthing.sh b/tools/check-doc-truthing.sh index a939e92c..c8328c4a 100755 --- a/tools/check-doc-truthing.sh +++ b/tools/check-doc-truthing.sh @@ -55,11 +55,14 @@ MATRIX="docs/CAPABILITY-MATRIX.adoc" # Docs that historically over-claim and MUST carry a pointer back at $MATRIX # (DOC-04). Each must mention CAPABILITY-MATRIX.adoc somewhere in its body. +# Listed as extension-less stems and resolved to whichever of .adoc/.md is +# present (.adoc preferred), so a .md<->.adoc migration (DOC-FORMAT) does not +# break this presence check the way a hard-coded extension would. BANNERED_DOCS=( - "README.adoc" - "docs/architecture/BACKEND-IMPLEMENTATION.md" - "docs/reference/COMPILER-CAPABILITIES.md" - "docs/history/ALPHA-1-RELEASE-NOTES.md" + "README" + "docs/architecture/BACKEND-IMPLEMENTATION" + "docs/reference/COMPILER-CAPABILITIES" + "docs/history/ALPHA-1-RELEASE-NOTES" ) # The machine-readable mirror (DOC-05): it follows the matrix, it does not @@ -142,9 +145,15 @@ else fi # --- 2. Every over-claiming doc still points back at the matrix (DOC-04) ----- -for doc in "${BANNERED_DOCS[@]}"; do - if [ ! -f "$doc" ]; then - note "ERROR: bannered doc is missing: $doc" +for stem in "${BANNERED_DOCS[@]}"; do + # Resolve the stem to whichever extension is present (.adoc preferred), so a + # .md<->.adoc migration does not trip the presence check. + doc="" + for ext in adoc md; do + if [ -f "$stem.$ext" ]; then doc="$stem.$ext"; break; fi + done + if [ -z "$doc" ]; then + note "ERROR: bannered doc is missing: $stem.{adoc,md}" note " If it was intentionally removed, drop it from BANNERED_DOCS" note " in this guard. Otherwise restore the file + its banner." fail=1 diff --git a/tools/doc-overclaims.allow b/tools/doc-overclaims.allow index f7b2ab4d..aab5f0ed 100644 --- a/tools/doc-overclaims.allow +++ b/tools/doc-overclaims.allow @@ -11,13 +11,13 @@ docs/ROADMAP.adoc * Production-ready toolchain docs/ROADMAP.adoc |Production ready docs/STATE-2026-05-26.adoc |*Phase 3 (Q3 2026)* |Production ready |*1.0* |requires Stage E (typed-wasm contract widening — cross-repo) -docs/architecture/BACKEND-IMPLEMENTATION.md > *production-ready*. One reference target (WASM); Deno-ESM/Node-CJS solid; +docs/architecture/BACKEND-IMPLEMENTATION.adoc _code-generators exist_, not _production-ready_. One reference target docs/bindings-roadmap.adoc |Production backend default; pairs with SQLite for dev. -docs/guides/WHAT-MAKES-IT-BRILLIANT.md **Q: When will it be production-ready?** -docs/history/ALPHA-1-RELEASE-NOTES.md - Production-ready -docs/history/ALPHA-1-RELEASE-NOTES.md - Production-ready compiler -docs/history/PHASE3-ASSESSMENT.md - Row polymorphism is production-ready! ✅ -docs/history/PHASE3-COMPLETE.md - **Production-ready** type system -docs/history/PHASE3-SESSION-SUMMARY.md - ✅ Row polymorphism is production-ready -docs/history/PHASE3-SESSION-SUMMARY.md | Row Polymorphism | 100% ✅ | Production ready | -docs/standards/ROADMAP.md This roadmap outlines the path from current state (lexer + parser) to a complete, production-ready language. +docs/guides/WHAT-MAKES-IT-BRILLIANT.adoc *Q: When will it be production-ready?* A: Aiming for compiler {plus} +docs/history/ALPHA-1-RELEASE-NOTES.adoc * Production-ready +docs/history/ALPHA-1-RELEASE-NOTES.adoc * Production-ready compiler +docs/history/PHASE3-ASSESSMENT.adoc *Good News:* - Row polymorphism is production-ready! ✅ - Effect +docs/history/PHASE3-COMPLETE.adoc *Lambda scope bug fixed* (bonus!) - *Production-ready* type system +docs/history/PHASE3-SESSION-SUMMARY.adoc Key accomplishments: - ✅ Row polymorphism is production-ready - ✅ +docs/history/PHASE3-SESSION-SUMMARY.adoc |Row Polymorphism |100% ✅ |Production ready +docs/standards/ROADMAP.adoc to a complete, production-ready language.